Package org.machanism.machai.gw.processor

package org.machanism.machai.gw.processor

Provides the project-aware processing layer used by Ghostwriter to traverse projects and submit file, guidance, or act prompts to a configured GenAI provider.

AbstractFileProcessor supplies the common filesystem behavior: recursive module discovery, optional concurrent module processing, include matching with glob: or regex: patterns, exclusion rules, non-recursive scans, and delegation to subclasses for each matching file.

AI file processing

AIFileProcessor adds provider execution and project context. It combines system instructions with prompts, supports YAML front matter, and accepts gw.model and enabledTools prompt properties. Prompt and instruction text can substitute public configuration values such as ${public.projectName}. Lines beginning with >>> recursively include UTF-8 content from HTTP(S) URLs or project-relative file:// references. In interactive mode, . terminates processing and > accepts the current response. Each request also receives JSON metadata for the project-relative file path, processing mode, and operating-system name.

 AIFileProcessor processor = new AIFileProcessor(
     new java.io.File("."), configurator, "openai:gpt-4.1");
 processor.setInstructions("Follow the project coding standards.");
 processor.setDefaultPrompt(">>> file://docs/review.md");
 processor.processFolder(projectLayout);
 

Guidance processing

GuidanceProcessor locates @guidance: comments in supported file types. Reviewer implementations are discovered with ServiceLoader; a reviewer extracts the mandatory instructions while retaining the marker in its original source location. A configured default prompt can process supported files without an explicit guidance block. Processing results are exposed as a report containing relative file paths and provider messages through GuidanceProcessor.getReport().

Act workflows

ActProcessor loads TOML acts from classpath resources, local directories, explicit files, or HTTP(S) locations. Custom acts may inherit another act with basedOn and ${super.value}. The > shorthand creates an ad-hoc task; public.prompt supplies user prompt text; # selects episodes, comma separates multiple selections, and ! stops normal-order continuation. Act model, instruction, input, thread, exclusion, recursion, and interactive settings are applied to the inherited configuration. Outputs are collected by ActProcessor.getResults().

 ActProcessor acts = new ActProcessor(
     new java.io.File("."), "openai:gpt-4.1", configurator);
 acts.setActsLocation("acts");
 acts.setAct("review#1,3! Check concurrency and error handling");
 acts.processFolder(projectLayout);
 java.util.List<String> results = acts.getResults();
 

Episodes and context

Episodes stores ordered prompts, supports regular or selected-order execution, repeats, moves by numeric ID or markdown heading, and exposes serializable episode metadata. ProjectContextKey names the operating system, project, parent-project, layout, source, test, documentation, and module values registered for project-context tools. GWConstants centralizes processor configuration keys, and EpisodeNotFoundException reports an unresolved episode heading.

Ghostwriter is the command-line entry point. Guidance mode is used when no act is selected; act mode runs a named workflow. Embedders should provide a configured Configurator, model/provider, and ProjectLayout. Providers and reviewers are supplied through the application's configuration and service registrations.

Class	Description
AbstractFileProcessor	Base implementation for processors that traverse a project directory and perform work on files and folders.
ActProcessor	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.
AIFileProcessor	File processor that drives a configured Genai provider with project-aware context, prompt metadata, optional external prompt inclusions, public configuration substitution, and function-tool registration.
EpisodeNotFoundException	Exception thrown when an episode cannot be resolved by name.
Episodes	Maintains an ordered collection of act episode prompts and provides execution helpers that support several playback strategies.
Ghostwriter	Command-line entry point for the Ghostwriter application.
Ghostwriter.RuntimeSettings	Mutable holder for startup settings resolved before processor creation.
GuidanceProcessor	Processes project files that contain inline guidance comments and dispatches the extracted instructions to the configured AI provider.
GWConstants	Central constants used by Ghostwriter configuration and runtime processing.
ProjectContextKey	Represents the context metadata keys used for evaluating and storing project layouts.