Usage:
aigenpipeline [options] [<input_files>...]
or
ai-gen-pipeline <command_file>

The AIGenPipeline tool generates content using an AI based on a prompt and input files.
It can also update or improve existing content, and it only calls the AI if the input or prompt files have changed.

If it's called with a command file, it reads a number of command lines from that file. Empty lines separate individual command lines.
Lines starting with a # are ignored (comments). This saves the startup time when calling the tool multiple times.

Options:

  General options:
    -h, --help               Show this help message and exit.
    -ha, --helpai <question> Answer a question about the tool from the text on its documentation site and exit.
                             Use as last argument - rest of command line counts as question.
    --version                Show the version of the AIGenPipeline tool and exit.
    -c, --check              Only check if the output needs to be regenerated based on input versions without actually 
                             generating it. The exit code is 0 if the output is up to date, 1 if it needs to be 
                             regenerated.
    -n, --dry-run            Enable dry-run mode, where the tool will only print to stderr what it would do without 
                             actually calling the AI or writing any files.
    -v, --verbose            Enable verbose output to stderr, providing more details about the process.

  Input / outputs:
    -o, --output <file>      Specify the output file where the generated content will be written.
    -ifp, --infileprompt <marker> <file>  The output and the prompt are in the same file, the marker is used in separating the parts.
    -upd, --update           Gives the current content of the output as hint to the AI that it should be updated / improved.
    --hint <file>            Gives this file as additional clue to the AI (special filename - is stdin), e.g. to tell
                             it to focus on something for an --update. This is not used for version checking.
    -p, --prompt <file>      Reads a prompt from the given file.
    -s, --sysmsg <file>      Optional: Reads a system message from the given file instead of using the default.
    -k <key>=<value>         Sets a key-value pair replacing ${key} in prompt files with the value. 
    -os, --outputscan <pattern>  Searches for files matching the ant-like pattern and scans them for AIGenPromptStart markers.
                             The infile prompts in these files are processed (see -ifp).
    -dd, --dependencydiagram Print a dependency diagram (Mermaid graph) of the scanned files and exit.

  AI Generation control:
    -f, --force              Force regeneration of output files, ignoring any version checks - same as -ga.
    -ga, --gen-always        Generate the output file always, ignoring version checks.
    -gn, --gen-notexists     Generate the output file only if it does not exist.
    -go, --gen-older         Generate the output file if it does not exist or is older than any of the input files.
    -gv, --gen-versioncheck  Generate the output file if the version of the input files has changed. (Default.)
    -wv, --write-version     Write the output file with a version comment. (Default.)
    -wvf, --write-versionfile Write the version comment to a separate file named like the output file with .version appended.
    -wo, --write-noversion   Write the output file without a version comment. Not compatible with default -gv .
    -wp, --write-part <marker> Replace the lines between the first occurrence of the marker and the second occurrence.
                             If a version marker is written, it has to be in the first of those lines and is changed there.
                             It is an error if the marker does not occur exactly twice; the output file has to exist.
    -e, --explain <question> Asks the AI a question about the generated result. This needs _exactly_the_same_command_line_
                             that was given to generate the output file, and the additional --explain <question> option.
                             It recreates the conversation that lead to the output file and asks the AI for a 
                             clarification. The output file is not written, but read to recreate the conversation.
                             Use as last argument - rest of command line counts as question.

  Configuration files:
    -cf, --configfile <file> Read configuration from the given file. These contain options like on the command line.
    -cn, --confignoscan      Do not scan for `.aigenpipeline` config files.
    -cne, --configignoreenv  Ignore the environment variable `AIGENPIPELINE_CONFIG`.
    -cp, --configprint       Print the collected configurations and exit.

  AI backend settings:
    -u, --url <url>          The URL of the AI server. Default is https://api.openai.com/v1/chat/completions .
                             In the case of OpenAI the API key is expected to be in the environment variable 
                             OPENAI_API_KEY, or given with the -a option.
    -a, --api-key <key>      The API key for the AI server. If not given, it's expected to be in the environment variable 
                             OPENAI_API_KEY, or you could use a -u option to specify a different server that doesnt need
                             an API key. Used in "Authorization: Bearer <key>" header.
    -org, --organization <id> The optional organization id in case of the OpenAI server.
    -m, --model <model>      The model to use for the AI. Default is gpt-4o .
    -t <maxtokens>           The maximum number of tokens to generate.
    -ns, --nosysmsg          For models that do not support system messages: give the system message as first user message.
                             Is done automatically if the model name starts with o[1-9].

Arguments:
  [<input_files>...]       Input files to be processed into the output file. 

Examples:
  Generate documentation from a prompt file:
    aigenpipeline -p prompts/documentation_prompt.txt -o generated_documentation.md src/foo/bar.java src/foo/baz.java

  Force regenerate an interface from an OpenAPI document, ignoring version checks:
    aigenpipeline -f -o specs/openapi.yaml -p prompts/api_interface_prompt.txt src/main/java/foo/MyInterface.java

  Ask how to improve a prompt after viewing the initial generation of specs/openapi.yaml:
    aigenpipeline -o PreviousOutput.java -p prompts/promptGenertaion.txt specs/openapi.yaml --explain "Why did you not use annotations?"

  Scan for files with infile prompts and (re-)generate the AI generated parts of those files:
    aigenpipeline -os "src/site/**/*.md"

Infile prompts:
  The idea is that files can contain both the prompt that has been used to generate their AI generated part(s) in a
  comment, and also instructions like the used input files or other settings. In such a file you would have e.g. 
  
  <!-- AIGenPromptStart(somemarker)
  (Here would come the prompt for the AI)
  AIGenCommand(somemarker)
  data.txt
  AIGenPromptEnd(somemarker) -->
  (Here is the generated content placed after calling aigenpipeline.)
  <!-- AIGenEnd(somemarker) -->
  
  That also means that it's not necessary to write a script that processes each of those files, but the tool can scan
  for AIGenPromptStart markers, as in the example `aigenpipeline -os "src/site/**/*.md"` above.

Configuration files:
  These contain options like on the command line. The environment variable `AIGENPIPELINE_CONFIG` can contain options.
  If -cn is not given, the tool scans for files named .aigenpipeline upwards from the output file directory.
  The order these configurations are processed is: environment variable, .aigenpipeline files from top to bottom,
  command line arguments. Thus the later override the earlier one, as these get more specific to the current call.
  Lines starting with a # are ignored in configuration files (comments).

Note:
  It's recommended to manually review and edit generated files. Use version control to manage and track changes over time. 
  More detailed instructions and explanations can be found at https://aigenpipeline.stoerr.net/ .
