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
Processes named action definitions (“acts”) and executes their prompts against a project, a project directory, or matching files by delegating the actual AI interaction to AIFileProcessor.

An act is loaded from a TOML definition. Definitions may be bundled on the classpath under "/acts/", provided from a configured local/remote act location, or referenced directly as an explicit ".toml" file. Built-in and custom definitions can be merged, and definitions can inherit another definition through the "basedOn" property. Inherited string and prompt-list values may use "${super.value}" to splice the parent value into the overriding value.

Supported command and configuration markers include:

  • ">" — shorthand prefix for an ad-hoc task act command.
  • "public.prompt" — property containing the user prompt visible to act templates.
  • "default" — TOML section prefix for default property values that are applied when no explicit value exists.
  • "#" — delimiter appended to an act name to select one or more episodes.
  • "," — separator for multiple selected episode numbers.
  • "!" — suffix for an episode selection that prevents subsequent normal-order episode execution.
  • "/acts/" and ".toml" — classpath location prefix and file extension used for built-in act definitions.
  • "basedOn" — property name used to declare act inheritance.
  • "http://" and "https://" — the supported remote act-location prefixes; non-URL locations are resolved from the project root.

Examples


 ActProcessor processor = new ActProcessor(projectDir, "openai:gpt-4o", configurator);
 processor.setAct("help");
 processor.process(projectLayout);

 // Run an ad-hoc task using the shorthand marker.
 processor.setAct("> summarize the project structure");

 // Run only episodes 1 and 3 of an act, then stop without continuing normally.
 processor.setAct("review#1,3! Check concurrency and error handling");

 // Use external TOML acts from a local directory or HTTPS location.
 processor.setActsLocation("acts");
 processor.setAct("custom-review");

  • Field Details

    • logger

      private static final org.slf4j.Logger logger
      Logger for documentation input processing events.

    • TOOL_AUTO_SEARCH_NAME

      private static final String TOOL_AUTO_SEARCH_NAME
      See Also:

    • actBundle

      final ResourceBundle actBundle
      Resource bundle supplying prompt templates for generators.

    • ACT_EXECUTION_INFORMATION_PREFIX

      private static final String ACT_EXECUTION_INFORMATION_PREFIX
      See Also:

    • DEFAULT_TASK_MARKER

      public static final String DEFAULT_TASK_MARKER
      Shorthand command prefix indicating that the raw prompt should be interpreted and executed directly as a standard, ad-hoc agent task command.

      When the input command begins with this marker, the runtime automatically expands the shorthand into a fully-qualified task command (e.g., > run build is processed as task run build).

      See Also:

    • SUPER_VALUE_PLACEHOLDER

      public static final String SUPER_VALUE_PLACEHOLDER
      Placeholder string used in inherited act definitions to reference and include the parent's value.
      See Also:

    • PUBLIC_USER_PROMPT_PROP_NAME

      public static final String PUBLIC_USER_PROMPT_PROP_NAME
      Property name representing the user prompt configured publicly inside the properties.
      See Also:

    • ACT_DEFAULT_PROPS_SECTION_NAME

      public static final String ACT_DEFAULT_PROPS_SECTION_NAME
      Prefix section designating default fallback values inside the loaded configurations.
      See Also:

    • STOP_SYMBOL

      public static final String STOP_SYMBOL
      Character symbol that triggers immediate termination and disables normal order progression.
      See Also:

    • SEPARATOR_CHARS

      public static final String SEPARATOR_CHARS
      Separator character used to delimit collection values like lists of files or episode indices.
      See Also:

    • EPISODE_DELIMETER

      public static final String EPISODE_DELIMETER
      Divider symbol linking the base act name to an optional explicit subset of episodes.
      See Also:

    • ACTS_BASENAME_PREFIX

      public static final String ACTS_BASENAME_PREFIX
      Classpath base directory for built-in act definitions.
      See Also:

    • TOML_EXTENSION

      public static final String TOML_EXTENSION
      Expected file extension for configurations parsed as TOML files.
      See Also:

    • BASED_ON_PROPERTY_NAME

      public static final String BASED_ON_PROPERTY_NAME
      Key used to denote inheritance by naming the base configuration to extend.
      See Also:

    • FIRST_WHITESPACE

      private static final Pattern FIRST_WHITESPACE
      Pre-compiled regex pattern to identify the first whitespace character in arguments.

    • HTTP_PREFIX

      private static final String HTTP_PREFIX
      Protocol prefix for standard unsecured HTTP endpoints.
      See Also:

    • HTTPS_PREFIX

      private static final String HTTPS_PREFIX
      Protocol prefix for secured HTTPS endpoints.
      See Also:

    • actsLocation

      private String actsLocation
      Optional directory containing external *.toml act files.

    • episodes

      private final Episodes episodes
      The episodes container managed by this processor.

    • disableNormalOrder

      private boolean disableNormalOrder
      Whether normal sequential execution should be skipped after explicit episode processing.

    • results

      private List<String> results
      List of collected outputs generated during processing.

    • actProperties

      private Map<String,Object> actProperties
      Map holding the accumulated act configuration properties loaded for execution.

    • autoToolsMap

      private Map<String,String[]> autoToolsMap
      Cached automatically selected tools, keyed by act name and episode ID.

    • INSTRUCTIONS_PROPERTY_NAME

      public static final String INSTRUCTIONS_PROPERTY_NAME
      TOML property name containing the instructions supplied to the AI provider for an act.
      See Also:

    • INPUTS_PROPERTY_NAME

      public static final String INPUTS_PROPERTY_NAME
      TOML property name containing prompt inputs/episodes.
      See Also:

  • Constructor Details

    • ActProcessor

      public ActProcessor(File projectDir, String genai, Configurator configurator)
      Creates an act processor.
      Parameters:
      projectDir - root directory used as a base for relative paths
      genai - provider key/name (including model)
      configurator - configuration source

  • Method Details

    • setAct

      public void setAct(String act) throws IOException
      Configures and initializes the current execution Action (Act) context by parsing the raw command string.

      This method orchestrates the early stage lifecycle of an action. It handles:

      1. Task Shorthand Expansion: Converting shortcut inputs (beginning with DEFAULT_TASK_MARKER) into standard task instructions.
      2. Fallback Fallback Defaults: Defaulting blank actions to "help".
      3. Token/Argument Extraction: Parsing the action name (first contiguous word) and separating it from any trailing, inline text prompt.
      4. Episode Slicing: Extracting targeted sub-episode qualifiers appended via the EPISODE_DELIMETER (e.g., my-act#2).
      5. Property Binding: Loading the action files, applying schema defaults, binding prompt argument placeholders, and configuring the target LLM runner model if overridden.

      Example Parse Formats

      • "> build-docs" expands to "task build-docs"
      • "bindex/java/mvn-project" runs the full 'bindex/java/mvn-project' action using the default prompt
      • "bindex/java/mvn-project#2" runs only the 2nd episode of the 'bindex/java/mvn-project' action
      • "bindex/java/mvn-project -Dkey=val" runs 'bindex/java/mvn-project' and extracts the arguments into actProperties
      Parameters:
      act - the raw command or action string to parse and execute (e.g., "task run", ">add javadoc", "bindex/java/mvn-project#2! use -DskipTests=true")
      Throws:
      IOException - if an error occurs while loading the action definitions from the target storage location

    • applyDefaultValues

      private void applyDefaultValues(Map<String,Object> actData)
      Populates default properties from the act data, applying configurations and falling back to active configurator values when required.
      Parameters:
      actData - the act data map containing raw values

    • applyPromptValues

      private void applyPromptValues(String prompt, Map<String,Object> actData)
      Configures user prompt metadata, falling back to act-specified defaults if empty.
      Parameters:
      prompt - the raw prompt to apply
      actData - target act properties map

    • applyEpisodeSelection

      private void applyEpisodeSelection(String episodeSelection)
      Parses and registers specified episode boundaries from an argument string.
      Parameters:
      episodeSelection - boundary definitions containing index selectors and flags

    • 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, File rootDir) 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 a 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 a 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
      rootDir - project root used to resolve relative act locations
      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 results, 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, File rootDir) throws IOException
      Attempts to load an act definition from a user-defined directory.
      Parameters:
      properties - destination for parsed dotted properties
      name - act name (without .toml)
      actsLocation - directory containing *.toml act files (may be null)
      rootDir - project root used to resolve relative act locations
      Returns:
      parsed TOML results, or null when not found
      Throws:
      IOException - if the file cannot be read

    • getAbsolutePath

      private static String getAbsolutePath(String name, String actsLocation, File rootDir) throws IOException
      Resolves an act file path or URL from an act name and configured act source.
      Parameters:
      name - act name or file path
      actsLocation - base directory or URL for act definitions
      rootDir - project root used to resolve relative act locations
      Returns:
      absolute file path or URL string
      Throws:
      IOException - if an explicitly referenced local act file does not exist

    • loadActToml

      private static org.tomlj.TomlParseResult loadActToml(String name) throws IOException
      Loads and parses an act TOML document from a local file or remote URL.
      Parameters:
      name - absolute file path or URL to the TOML resource
      Returns:
      parsed TOML results, or null if a local file path does not exist
      Throws:
      IOException - if reading the TOML resource fails

    • isAbsolute

      private static boolean isAbsolute(String name)
      Determines whether the supplied act reference should be treated as an explicit TOML path.
      Parameters:
      name - act reference to inspect
      Returns:
      true if the reference already ends with .toml

    • setActData

      static void setActData(Map<String,Object> properties, org.tomlj.TomlParseResult toml)
      Copies dotted-string keys from the TOML parse results into properties.

      If a 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 results

    • setActDataEntry

      private static void setActDataEntry(Map<String,Object> properties, Map.Entry<String,Object> entry)
      Applies a single TOML entry to the merged act property map.
      Parameters:
      properties - destination property map
      entry - TOML entry to process

    • putStringActData

      private static void putStringActData(Map<String,Object> properties, String key, String value)
      Stores a string property, merging it with any inherited value already present.
      Parameters:
      properties - destination property map
      key - property name
      value - property value from the current act

    • mergeStringWithListValue

      private static List<String> mergeStringWithListValue(List<String> mainValueList, String value, String key)
      Merges a single string value into each string item of an inherited list.
      Parameters:
      mainValueList - inherited list value
      value - string value to merge through SUPER_VALUE_PLACEHOLDER
      key - property name whose values are being merged
      Returns:
      merged list results

    • mergeTomlArrayValues

      private static List<String> mergeTomlArrayValues(Object existingValue, List<Object> values, String key)
      Merges TOML array values with any existing inherited string or list value.
      Parameters:
      existingValue - existing property value, if any
      values - TOML array values from the current act
      key - property name whose values are being merged
      Returns:
      merged string list

    • toStringList

      private static List<String> toStringList(Object existingValue)
      Converts an inherited property value to a list of strings.
      Parameters:
      existingValue - existing property value
      Returns:
      list representation of the value, or an empty list if unsupported

    • resolveMergedValue

      private static String resolveMergedValue(List<String> mainValues, int index, String value)
      Resolves a merged value for an inherited prompt slot.
      Parameters:
      mainValues - inherited values
      index - current position
      value - overriding value for the position
      Returns:
      merged value for the position

    • 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

    • applyStringActData

      private void applyStringActData(String key, String valueObj)
      Applies a single string property to processor state or configuration.
      Parameters:
      key - property name
      valueObj - property value as an Object

    • resolveInheritedValue

      private String resolveInheritedValue(String key, String value)
      Resolves a property value against the current configurator for inheritance.
      Parameters:
      key - property name
      value - act-defined value that may contain SUPER_VALUE_PLACEHOLDER
      Returns:
      resolved property value

    • applyStringProperty

      private void applyStringProperty(String key, String value)
      Applies a resolved string property by dispatching to the matching processor setting.
      Parameters:
      key - property name
      value - resolved property value

    • resolvePromptValues

      private List<String> resolvePromptValues(List<String> promptValues)
      Resolves inherited placeholders for each prompt episode.
      Parameters:
      promptValues - prompt values to resolve
      Returns:
      resolved prompt list

    • setActsLocation

      public void setActsLocation(String actsLocation)
      Sets the location used for loading external act definition files (*.toml).

      The location may be specified as:

      • An absolute path — used as-is (e.g., /opt/gw/acts).
      • A relative path — resolved against the root directory.
      • A URL — any value starting with http:// or https://, in which case acts are loaded remotely and no local directory validation is performed.
      For path-based (non-URL) locations, the resolved directory must already exist; otherwise an exception is thrown.

      A null value is ignored and leaves the current setting unchanged.

      Parameters:
      actsLocation - absolute path, relative path, or URL pointing to the directory (or remote source) containing act files; null to leave the current value unchanged
      Throws:
      IllegalArgumentException - if actsLocation is a non-URL path that does not resolve to an existing directory

    • 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 - active project layout metadata context to process
      Throws:
      IOException - if scanning or executing templates fails

    • process

      private String process(ProjectLayout projectLayout, File projectDir, String prompt, int episodeId)
      Executes a single episode prompt after prepending act metadata.
      Parameters:
      projectLayout - active project layout
      projectDir - file or directory being processed
      prompt - episode prompt text
      episodeId - zero-based episode index
      Returns:
      provider results string, if any

    • applyTools

      protected void applyTools(String instructions, String[] prompts, Genai provider, String[] tools)
      Applies the tools configured for an act episode, including automatic tool selection requested through the episode's YAML front matter.

      Set enabledTools: auto to have a separate provider request select the applicable tools from the episode instructions and prompt. The selected tool names are cached for the act episode, then registered on the provider for the actual request. For example: 

      
 ---
 enabledTools: auto
 ---
 Review this module and use only the tools needed for the task.

      A YAML mapping can give the automatic selector additional constraints. Its auto value is passed to the selector as a query; it guides selection rather than directly disabling tools. For example: 

      
 ---
 enabledTools:
   auto: Don't use web access and system command tools.
 ---
 Analyze the local implementation.

      Any other enabledTools value is delegated unchanged to the standard tool-registration behavior.

      Overrides:
      applyTools in class AIFileProcessor
      Parameters:
      instructions - resolved system instructions for the episode
      prompts - resolved prompt parts, including episode metadata
      provider - provider that receives the selected tools
      tools - configured tool names or automatic-selection marker

    • isAutoToolSelection

      private boolean isAutoToolSelection(String toolValue)
      Determines whether a front-matter tool value requests automatic selection.
      Parameters:
      toolValue - serialized scalar or YAML mapping value
      Returns:
      true when the value is auto or an auto mapping

    • getAutoToolSelectionQuery

      private String getAutoToolSelectionQuery(String toolValue)
      Extracts the optional query from SnakeYAML's serialized auto mapping value.
      Parameters:
      toolValue - serialized scalar or YAML mapping value
      Returns:
      query text, or an empty string for a plain auto marker

    • getAutoTools

      private String[] getAutoTools(String query, String instructions, String[] prompts)
      Selects and caches the tools required for the current act episode by asking the configured provider for a JSON tool list.
      Parameters:
      instructions - provider instructions; retained for the selection context
      query -
      prompts - prompt parts containing act execution metadata and the episode prompt
      Returns:
      selected tool names, or null when selection fails
      Throws:
      IllegalArgumentException - if the provider returns malformed JSON

    • getInputId

      private String getInputId(String[] prompts) throws com.fasterxml.jackson.core.JsonProcessingException
      Builds the cache key for an act episode from the execution metadata in the prompt.
      Parameters:
      prompts - prompt parts containing serialized act execution metadata
      Returns:
      cache key composed of the act name and current episode ID
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException - if the execution metadata is not valid JSON

    • processFile

      protected void processFile(ProjectLayout projectLayout, File file) throws IOException
      Executes the act against a single file.
      Overrides:
      processFile in class AbstractFileProcessor
      Parameters:
      projectLayout - project layout
      file - file to process
      Throws:
      IOException - if provider execution fails

    • addResults

      public void addResults(String result)
      Appends a string result item to the execution list.
      Parameters:
      result - result message or payload to record

    • getResults

      public List<String> getResults()
      Returns the list of all collected outputs.
      Returns:
      the collected list of run outputs

    • getActProperties

      public Map<String,Object> getActProperties()
      Returns the merged act properties currently loaded on this processor.
      Returns:
      the act properties map