Ghostwriter 1.4.2-SNAPSHOT API
Ghostwriter API
Ghostwriter is an advanced documentation engine that automatically scans,
analyzes, and assembles project documentation using embedded guidance tags
and AI-powered synthesis. This API overview describes the
Ghostwriter project and its documentation-processing purpose.
It supports all types of project files, including source code,
documentation, project site content, and other relevant files.
The project is organized around a processor layer that discovers project files and workflow context, a reviewer layer that extracts format-specific guidance, and a tools layer that exposes controlled operations to AI-driven workflows. Together these packages provide the behavior described by their package-level API documentation.
The API provides a project-aware processing pipeline. Processors discover files and workflow context, resolve configuration and prompts, and invoke generative-AI providers. Format-specific reviewers extract embedded guidance, while functional AI tools provide controlled access to project files, commands, web content, reusable Acts, and project-scoped workflow state.
Architecture
The diagram summarizes the principal types and their relationships. Processor classes orchestrate guidance and Act workflows; reviewers supply file-format-specific guidance extraction; and tool providers expose the controlled operations used by those workflows. The processor layer also supplies traversal, configuration, prompt inclusion, provider selection, and ordered episode execution around the project layout.
Packages
- org.machanism.machai.gw.processor
- Provides project-file processors and the command-line workflow. It discovers modules and files, supports recursive traversal and path matching, resolves providers and prompts, expands project-relative or web prompt inclusions, and processes files, folders, modules, and patterns. Guidance processing selects format reviewers and records reports; Act processing loads inherited TOML definitions and executes ordered, selected, repeated, or navigated episodes with workflow metadata.
- org.machanism.machai.gw.reviewer
-
Provides the file-format-specific review layer. Its service-provider
interface and implementations locate
@guidanceinstructions in Java, HTML/XML, Markdown, PlantUML, Python, TypeScript, and dedicated guidance text files, then turn them into localized prompt fragments. Reviewers apply each format's comment conventions, preserve project- relative file context, read source content as UTF-8, and return no fragment when relevant guidance is absent. - org.machanism.machai.gw.tools
- Provides the Functional AI Tools and workflow infrastructure used by providers. Tool groups expose controlled file, command, web, Act, guidance, and project-context operations, including file editing, validated patch application, command safety checks, bounded command-log access, asynchronous result polling, and workflow navigation. Prompt templates and tool metadata allow AI-driven workflows to use these operations while project paths and execution context remain controlled.
Typical use
Use the processor package to run a guidance-driven documentation update or a named Act against a project layout. The processor selects reviewers for candidate files, passes the resulting instructions to the configured AI provider, and registers the appropriate tool providers for the workflow. The tools package supplies project-scoped operations that the provider can invoke, while the reviewers package keeps guidance extraction consistent with each file format. Package-level documentation provides the detailed contracts and relationships for each part of this pipeline.