aia 0.4.4 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84dc61c76d34c0a5c37db65b31c8412e3c81fb74b4aa33bf6550747601948727
-  data.tar.gz: 481d77b6a396f420f260c517d74b66406197002e5350808f22bb2182cf1beff6
+  metadata.gz: be8cb1e68dc5f180c5a75b87ff6519ccda00a7e82a5da524577648d83f2de56a
+  data.tar.gz: b16fc5cf5e15ee1942da68b832f82308a2cd037d3374d8a55bdbe2289be1b030
 SHA512:
-  metadata.gz: b241f244f12d35b26ebaec39eeedbf709784e49b3f5b3e79bbd3bbf636f7b2bdc225924fda305a99a366c1880b222b2b40de3c2fb4d9117c63183ae6e2e9a114
-  data.tar.gz: b9514f576ef22a7f828815cf50885014d64a7c4f1fa728fcfd2072b3a40708ec636aeb9fdc5cfd3fa7b9e0a6a39235690b6fea308dbf68c37b9c8492db75663c
+  metadata.gz: fa3136515303b071abe2866a48af9702047d117d004b6666150445133ebfa0ebb4c0aa1e86ebc3ea7e023ab6eed255a6a98938c7bf9bbb8c01a9f524130a87f4
+  data.tar.gz: 33d4e8aa6df5e3b3a3b7e5e5811af67e01be18498ce3818dbdd4a863b495132f07fec1333d6273953132931b82852c6a435654fdac6d4aef57e14cd7f2f3ff81

data/.config/tocer/configuration.yml

@@ -0,0 +1,5 @@
+label: "## Table of Contents"
+patterns:
+  - "README.md"
+  - doc/*.md
+root_dir: "."

data/.semver

@@ -1,6 +1,6 @@
 ---
 :major: 0
-:minor: 4
-:patch: 4
+:minor: 5
+:patch: 1
 :special: ''
 :metadata: ''

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 ## [Unreleased]
-## [0.4.4] 2023-01-01
-- fixed first issue of the year.  Issue 14 with te --role option actually writing the role content into the prime prompts file.
+
+## [0.5.1] 2024-01-12
+- removed a wicked puts "loaded" statement
+- fixed missed code when the options were changed to --out_file and --log_file
+- fixed completion functions by updating $PROMPT_DIR to $AIA_PROMPTS_DIR to match the documentation.
+
+## [0.5.0] 2024-01-05
+- breaking changes:
+    - changed `--config` to `--config_file`
+    - changed `--env` to `--shell`
+    - changed `--output` to `--out_file`
+        - changed default `out_file` to `STDOUT`
 
 ## [0.4.3] 2023-12-31
 - added --env to process embedded system environment variables and shell commands within a prompt.

data/README.md

@@ -1,14 +1,15 @@
 # AI Assistant (AIA)
 
-`aia` is a command-line utility that integrates prameterized prompt management with generative AI (gen-AI) execution.
+`aia` is a command-line utility that facilitates interaction with AI models. It automates the management of pre-compositional prompts and executes generative AI (Gen-AI) commands on those prompts.
 
-Uses the gem "prompt_manager" to manage the prompts sent to the `mods` command-line utility.  Uses the command line tools "ripgrep" to search for prompts to send and "fzf" to select the prompts that match the search term.
+It leverages the `prompt_manager` gem to manage prompts for the `mods` and `sgpt` CLI utilities. It utilizes "ripgrep" for searching for prompt files.  It uses `fzf` for prompt selection based on a search term and fuzzy matching.
 
-**Most Recent Change**
+**Most Recent Change**: Refer to the [Changelog](CHANGELOG.md)
 
-v0.4.3 - Added the --env and --erb options.  Prompts can now be dynamic.
-v0.4.2 - Added a --role option to be prepended to a primary prompt.
-v0.4.1 - Added --chat and --speak options.  Prompt directives are now supported.
+v0.5.0 - Breaking changes: 
+- `--config` is now `--config_file`
+- `--env` is now `--shell`
+- `--output` is now `--out_file`
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -16,15 +17,20 @@ v0.4.1 - Added --chat and --speak options.  Prompt directives are now supported.
 
   - [Installation](#installation)
   - [Usage](#usage)
-  - [System Environment Variables (envar)](#system-environment-variables-envar)
-    - [System Environment Variables inside of a Prompt](#system-environment-variables-inside-of-a-prompt)
+  - [Configuration Using Envars](#configuration-using-envars)
+  - [Shell Integration inside of a Prompt](#shell-integration-inside-of-a-prompt)
+      - [Access to System Environment Variables](#access-to-system-environment-variables)
+      - [Dynamic Shell Commands](#dynamic-shell-commands)
   - [*E*mbedded *R*u*B*y (ERB)](#embedded-ruby-erb)
   - [Prompt Directives](#prompt-directives)
+    - [`aia` Specific Directive Commands](#aia-specific-directive-commands)
+      - [//config](#config)
+    - [Backend Directive Commands](#backend-directive-commands)
   - [All About ROLES](#all-about-roles)
     - [Other Ways to Insert Roles into Prompts](#other-ways-to-insert-roles-into-prompts)
   - [External CLI Tools Used](#external-cli-tools-used)
   - [Shell Completion](#shell-completion)
-  - [Ny Most Powerful Prompt](#ny-most-powerful-prompt)
+  - [My Most Powerful Prompt](#my-most-powerful-prompt)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
@@ -91,7 +97,7 @@ ARGUMENTS
 
 OPTIONS
        --chat begin a chat session with the backend after the initial prompt response;  will
-              set --no-output so that the backend response comes to STDOUT.
+              set --no-out_file so that the backend response comes to STDOUT.
 
        --completion SHELL_NAME
 
@@ -101,7 +107,8 @@ OPTIONS
               Invokes an editor on the prompt file.  You can make changes to the prompt file,
               save it and the newly saved prompt will be processed by the backend.
 
-       --env  This option tells aia to replace references to system environment variables in
+       --shell
+              This option tells aia to replace references to system environment variables in
               the prompt with the value of the envar.  envars are like $HOME and ${HOME} in
               this example their occurance will be replaced by the value of ENV[‘HOME’].
               Also the dynamic shell command in the pattern $(shell command) will be executed
@@ -132,7 +139,7 @@ OPTIONS
        -b, --[no]-backend LLM TOOL
               Specify the backend prompt resolver - default is mods
 
-       -c, --config PATH_TO_CONFIG_FILE
+       -c, --config_file PATH_TO_CONFIG_FILE
               Load Config File - default is nil
 
        -d, --debug
@@ -147,13 +154,13 @@ OPTIONS
        -h, --help
               Show Usage - default is false
 
-       -l, --[no]-log PATH_TO_LOG_FILE
+       -l, --[no]-log_file PATH_TO_LOG_FILE
               Log FILEPATH - default is $HOME/.prompts/prompts.log
 
        -m, --[no]-markdown
               Format with Markdown - default is true
 
-       -o, --[no]-output PATH_TO_OUTPUT_FILE
+       -o, --[no]-out_file PATH_TO_OUTPUT_FILE
               Out FILENAME - default is ./temp.md
 
        -p, --prompts PATH_TO_DIRECTORY
@@ -202,9 +209,9 @@ OpenAI ACCOUNT IS REQUIRED
 
 USAGE NOTES
        aia is designed for flexibility, allowing users to pass prompt ids and context files
-       as arguments. Some options change the behavior of the output, such as --output for
-       specifying a file or --no-output for disabling file output in favor of standard output
-       (STDPIT).
+       as arguments. Some options change the behavior of the output, such as --out_file for
+       specifying a file or --no-out_file for disabling file output in favor of standard
+       output (STDPIT).
 
        The --completion option displays a script that enables prompt ID auto-completion for
        bash, zsh, or fish shells. It’s crucial to integrate the script into the shell’s
@@ -250,9 +257,9 @@ AUTHOR
 AIA                                       2024-01-01                                   aia(1)
 ```
 
-## System Environment Variables (envar)
+## Configuration Using Envars
 
-The `aia` configuration defaults can be over-ridden by envars with the prefix "AIA_" followed by the config item name also in uppercase. All configuration items can be over-ridden in this way by an envar.  The following table show a few examples.
+The `aia` configuration defaults can be over-ridden by system environment variables *(envars)* with the prefix "AIA_" followed by the config item name also in uppercase. All configuration items can be over-ridden in this way by an envar.  The following table show a few examples.
 
 | Config Item   | Default Value | envar key |
 | ------------- | ------------- | --------- |
@@ -265,58 +272,123 @@ The `aia` configuration defaults can be over-ridden by envars with the prefix "A
 | log_file      | ~/.prompts/_prompts.log | AIA_LOG_FILE |
 | markdown      | true          | AIA_MARKDOWN |
 | model         | gpt-4-1106-preview | AIA_MODEL |
-| output_file   | temp.md       | AIA_OUTPUT_FILE |
+| out_file       | STDOUT        | AIA_OUT_FILE |
 | prompts_dir   | ~/.prompts    | AIA_PROMPTS_DIR |
 | VERBOSE       | FALSE         | AIA_VERBOSE |
 
 
-See the `@options` hash in the `cli.rb` file for a complete list.  There are some config items that do not necessarily make sense for use as an envar over-ride.  For example if you set `export AIA_DUMP=yaml` then `aia` would dump a config file in HAML format and exit every time it is ran until you finally did `unset AIA_DUMP`
+See the `@options` hash in the `cli.rb` file for a complete list.  There are some config items that do not necessarily make sense for use as an envar over-ride.  For example if you set `export AIA_DUMP=yaml` then `aia` would dump a config file in YAML format and exit every time it is ran until you finally did `unset AIA_DUMP`
 
 In addition to these config items for `aia` the optional command line parameters for the backend prompt processing utilities (mods and sgpt) can also be set using envars with the "AIA_" prefix.  For example "export AIA_TOPP=1.0" will set the "--topp 1.0" command line option for the `mods` utility when its used as the backend processor.
 
-### System Environment Variables inside of a Prompt
+## Shell Integration inside of a Prompt
 
-The cpmmand line option "--env" instructs `aia` to replace any system environment variable references in the prompt text with the value of the system envornment variable.  So patterns like $HOME and ${HOME} in the prompt will be replaced with the value of ENV['HOME'].
+Using the option `--shell` enables `aia` to access your terminal's shell environment from inside the prompt text.
 
-As an added bonus, dynamic content can be inserted into the prompt using the pattern $(shell command) where the output of the shell command will replace the $(...) pattern.
+#### Access to System Environment Variables
+
+`aia` can replace any system environment variable (envar) references in the prompt text with the value of the envar.  Patterns like $USER and ${USER} in the prompt will be replaced with that envar's value - the name of the user's account.  Any envar can be used.
+
+#### Dynamic Shell Commands
+
+Dynamic content can be inserted into the prompt using the pattern $(shell command) where the output of the shell command will replace the $(...) pattern.
+
+Consider the power to tailoring a prompt to your specific operating system:
+
+```
+As a system administration on a $(uname -v) platform what is the best way to [DO_SOMETHING]
+```
+
+or insert content from a file in your home directory:
+
+```
+Given the following constraints $(cat ~/3_laws_of_robotics.txt) determine the best way to instruct my roomba to clean my kids room.
+```
 
-That's enough power to get anyone into deep trouble.  Wait there's more coming.  Do you want a full programming language in your prompt?  Feel like running the prompt through ERB before sending it to the backend?  I've been thinking about it.  Should be a simple thing to do. Yes it was.
 
 ## *E*mbedded *R*u*B*y (ERB)
 
-The --erb options now submits the prompt text through the ERB parser for execution before environment variable, keyword and dynamic shell replace take place.  With this much dynamic prompt manipulation we should really be able to get into trouble!
+The inclusion of dynamic content through the shell integration provided by the `--shell` option is significant.  `aia` also provides the full power of embedded Ruby code processing within the prompt text.
+
+The `--erb` option turns the prompt text file into a fully functioning ERB template. The [Embedded Ruby (ERB) template syntax (2024)](https://bophin-com.ngontinh24.com/article/language-embedded-ruby-erb-template-syntax) provides a good overview of the syntax and power of ERB.
+
+Most websites that have information about ERB will give examples of how to use ERB to generate dynamice HTML content for web-based applications.  That is a common use case for ERB.  `aia` on the other hand uses ERB to generate dynamic prompt text.
 
-If you are not a Rubyist and do not know about ERB see this [webpage](https://ruby-doc.org/stdlib-3.0.0/libdoc/erb/rdoc/ERB.html) for some information about the power of embedded Ruby.
 
 ## Prompt Directives
 
-Downstream processing directives were added to the `prompt_manager` gem at version 0.4.1.  These directives are lines in the prompt text file that begin with "//"
+Downstream processing directives were added to the `prompt_manager` gem used by `au` at version 0.4.1.  These directives are lines in the prompt text file that begin with "//" having this pattern:
+
+```
+//command parameters
+```
+
+There is no space between the "//" and the command.
 
-For example if a prompt text file has this line:
+### `aia` Specific Directive Commands
 
-> //config chat? = true
+At this time `aia` only has one directive command `//config`
 
-That prompt will enter the chat loop regardles of the presents of a "--chat" CLI option or the setting of the envar AIA_CHAT.
+#### //config
 
-BTW did I mention that `aia` supports a chat mode where you can send an initial prompt to the backend and then followup the backend's reponse with additional keyboard entered questions, instructions, prompts etc.
+The `//config` directive within a prompt text file is used to tailor the specific configuration environment for the prompt.  All configuration items are available to have their values changed.  The order of value assignment for a configuration item starts with the default value which is replaced by the envar value which is replaced by the command line option value which is replaced by the value from the config file.
 
-See the [AIA::Directives](lib/aia/directives.rb) class to see what directives are available on the fromend within `aia`.
+The `//config` is the last and final way of changing the value for a configuration item for a specific prompt.
 
-See the [AIA::Mods](lib/aia/tools/mods.rb) class to for directives that are available to the `mods` backend.
+The switch options are treated like booleans.  They are either `true` or `false`. Their name within the context of a `//config` directive always ends with a "?" character - question mark.
 
-See the [AIA::Sgpt](lib/aia/tools/sgpt.rb) class to for directives that are available to the `sgpt` backend.
+To set the value of a switch using ``//config` for example `--terse` or `--chat` to this:
+
+```
+//config chat? = true
+//config terse? = true
+```
+
+A configuration item such as `--out_file` or `--model` has an associated value on the command line.  To set that value with the `//config` directive do it like this:
+
+```
+//config model = gpt-3.5-turbo
+//config out_file = temp.md
+//config backend = mods
+```
+
+### Backend Directive Commands
+
+See the source code for the directives supported by the backends which at this time are configuration-based as well.
+
+- [mods](lib/aia/tools/mods.rb)
+- [sgpt](lib/aia/tools/sgpt.rb)
+
+FOr example `mods` has a configuration item `topp` which can be set by a directive in a prompt text file directly.
+
+```
+//topp 1.5
+```
+
+If `mods` is not the backend the `//topp` direcive is ignored.
 
 ## All About ROLES
 
-`aia` provides the "-r --role" CLI option to identify a prompt ID within your prompts directory which defines the context within which the LLM is to provide its response.  The text of the role ID is pre-pended to the text of the primary prompt to form a complete prompt to be processed by the backend.
+`aia` provides the `--role` CLI option to identify a prompt ID within your prompts directory which defines the context within which the LLM is to provide its response.  The text of the role ID is pre-pended to the text of the primary prompt to form a complete prompt to be processed by the backend.
 
 For example consider:
 
-> aia -r ruby refactor my_class.rb
+```shell
+aia -r ruby refactor my_class.rb
+```
+
+Within the prompts directory the contents of the text file `ruby.txt` will be pre-pre-pended to the contents of the `refactor.txt` file to produce a complete prompt.  That complete prompt will have any parameters then directives processed before sending the prompt text to the backend.
 
-Within the prompts directory the contents of the text file `ruby.txt` will be pre-pre-pended to the contents of the refactor.txt file to produce a complete prompt.  That complete prompt will have any parameters then directives processed before sending the prompt text to the backend.
+Note that `--role` is just a way of saying add this prompt text file to the front of this other prompt text file.  The contents of the "role" prompt could be anything.  It does not necessarily have be an actual role.
+
+You might consider have a sub-directory of your `prompts_dir` name `role` in which you put the prompt files that describe the various roles that you commonly use with your prompts.  `aia` fully supports a directory tree within the `prompts_dir` as a way of organization or classification of your different prompt text files.
+
+```shell
+aia -r roles/sw_eng doc_the_methods my_class.rb
+```
+
+In this example the prompt text file `$AIA_PROMPTS_DIR/roles/sw_eng.txt` is prepended to the prompt text file `$AIA_PROMPTS_DIR/doc_the_methods.txt`
 
-Note that "role" is just a way of saying add this prompt to the front of this other prompt.  The contents of the "role" prompt could be anything.  It does not necessarily have be an actual role.
 
 ### Other Ways to Insert Roles into Prompts
 
@@ -360,13 +432,15 @@ export EDITOR="subl -w"
 
 You can setup a completion function in your shell that will complete on the prompt_id saved in your `prompts_dir` - functions for `bash`, `fish` and `zsh` are available.  To get a copy of these functions do this:
 
-> `aia --completion bash`
+```shell
+aia --completion bash
+```
 
 If you're not a fan of "born again" replace `bash` with one of the others.
 
 Copy the function to a place where it can be installed in your shell's instance.  This might be a `.profile` or `.bashrc` file, etc.
 
-## Ny Most Powerful Prompt
+## My Most Powerful Prompt
 
 This is just between you and me so don't go blabbing this around to everyone.  My most power prompt is in a file named `ad_hoc.txt`. It looks like this:
 
@@ -376,11 +450,17 @@ Yep.  Just a single parameter for which I can provide a value of anything that i
 
 Which do you think is better to have in your shell's history file?
 
-> mods "As a certified public accountant specializing in forensic audit and analysis of public company financial statements, what do you think of mine?  What is the best way to hide the millions dracma that I've skimmed?"  < financial_statement.txt
+```shell
+mods "As a certified public accountant specializing in forensic audit and analysis of public company financial statements, what do you think of mine?  What is the best way to hide the millions dracma that I've skimmed?"  < financial_statement.txt
+```
 
-> aia ad_hoc financial_statement.txt
+or
 
-Both do the same thing; however, aia does not put the text of the prompt into the shell's history file.... of course the keyword/parameter value is saved in the prompt's JSON file and the prompt with the response are logged unless --no-log is specified; but, its not messing up the shell history!
+```shell
+aia ad_hoc financial_statement.txt
+```
+
+Both do the same thing; however, `aia` does not put the text of the prompt into the shell's history file.... of course the keyword/parameter value is saved in the prompt's JSON file and the prompt with the response are logged unless `--no-log` is specified; but, its not messing up the shell history!
 
 ## Development
 
@@ -394,16 +474,9 @@ I've designed `aia` so that it should be easy to integrate other backend LLM pro
 
 When you find problems with `aia` please note them as an issue.  This thing was written mostly by a human and you know how error prone humans are.  There should be plenty of errors to find.
 
-Also I'm interested in doing more with the prompt directives.  I'm thinking that there is a way to include dynamic content into the prompt computationally.  Maybe something like tjos wpi;d be easu tp dp:
-
-> //insert url https://www.whitehouse.gov/briefing-room/
-> //insert file path_to_file.txt
-
-or maybe incorporating the contents of system environment variables into prompts using $UPPERCASE or $(command) or ${envar_name} patterns.
-
-I've also been thinking that the REGEX used to identify a keyword within a prompt could be a configuration item.  I chose to use square brackets and uppercase in the default regex; maybe, you have a collection of prompt files that use some other regex.  Why should it be one way and not the other.
+I've been thinking that the REGEX used to identify a keyword within a prompt could be a configuration item.  I chose to use square brackets and uppercase in the default regex; maybe, you have a collection of prompt files that use some other regex.  Why should it be one way and not the other.
 
-Also I'm not happy with the way where I hve some command line options for external command hard coded.  I think they should be part of the configuration as well.  For example the way I'm using `rg` and `fzf` may not be the way that you want to use them.
+Also I'm not happy with the way where I a some command line options for external command hard coded.  I think they should be part of the configuration as well.  For example the way I'm using `rg` and `fzf` may not be the way that you want to use them.
 
 ## License
 

data/doc/aia_and_pre_compositional_prompts.md

@@ -0,0 +1,474 @@
+## AIA and Pre-compositional AI Prompts
+
+Pre-compositional templating of prompts using `AIA` endows prompt engineers with a significant level of power typically reserved for specialized gen-AI applications. `AIA` is a versatile command-line utility, with capabilities limited only by the imagination behind the prompts you create.
+
+A pre-compositional prompt acts as a foundational template, which can be expanded into a fully fleshed-out prompt. This prompt is then handed off to a generative AI processor to transform into a response that meets your specific requirements.
+
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+  - [Introduction](#introduction)
+    - [Large Language Models (LLM)](#large-language-models-llm)
+    - [Running AIA](#running-aia)
+    - [Set Up a Prompts Directory](#set-up-a-prompts-directory)
+  - [AIA Supports Parameterized Prompts](#aia-supports-parameterized-prompts)
+    - [Create a Parameterized Prompt](#create-a-parameterized-prompt)
+    - [The Next Parts](#the-next-parts)
+  - [Comments](#comments)
+    - [Line Comments](#line-comments)
+    - [End of File Block Comment](#end-of-file-block-comment)
+  - [Directives](#directives)
+    - [The `config` Directive](#the-config-directive)
+    - [Parameter Substitution in Directives](#parameter-substitution-in-directives)
+  - [Shell Integration](#shell-integration)
+    - [Accessing System Environment Variables](#accessing-system-environment-variables)
+      - [Contextual System Environment Variables](#contextual-system-environment-variables)
+    - [Invoking Shell Commands](#invoking-shell-commands)
+  - [Harnessing Ruby's Capabilities](#harnessing-rubys-capabilities)
+    - [The Concept of Binding](#the-concept-of-binding)
+    - [ERB Syntax at a Glance](#erb-syntax-at-a-glance)
+    - [Conditional Logic](#conditional-logic)
+    - [Accessing Current Data](#accessing-current-data)
+  - [Summary of AIA Command-Line Tool](#summary-of-aia-command-line-tool)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
+
+
+## Introduction
+
+The pre-compositional prompt management as utilized by the `AIA` (AI Assistant) command-line utility are a powerful extension to using the GPT technology in the terminal. If terminal programs and command-line interfaces (CLIs) aren't part of your workflow, then the current version of `AIA` may not be suitable for you.
+
+`AIA` requires a Ruby environment.  To install and run `AIA` you must have Ruby installed on your system.  If you are not sure if your system has Ruby installed do this in your terminal to find out:
+
+```shell
+ruby --version
+```
+
+To install Ruby on your machine, follow the official [Ruby installation guide](https://www.ruby-lang.org/en/documentation/installation/).
+
+With Ruby installed, you can set up `AIA` through your terminal with this command:
+
+```shell
+gem install aia
+```
+
+For the full potential of `AIA`, these CLI utilities are also needed:
+
+```shell
+brew install ripgrep fzf mods
+```
+
+For operating systems other than macOS, such as Linux or Windows, use their respective package managers (`apt`, `yum`, `dnf`, `scoop`, `choco`, etc.) to install the following tools:
+
+- `ripgrep`: An advanced search tool akin to `grep`.
+- `fzf`: A versatile command-line fuzzy finder.
+- `mods`: An AI-enhanced command-line tool for processing the outputs of other commands.
+
+### Large Language Models (LLM)
+
+LLMs and GPTs (Generative Pre-trained Transformers) have sparked a revolution in AI by predicting text, word, sentence, pixel, and sound sequences that fit patterns initiated by a user prompt.  This revolution started when computer scientist realized that syntactic approaches to language translations were ineffective in creating good translations.  A statistical approach was created in which the probabilities of one set of language characters or phrases meant the same as another languages characters or phrases.
+
+For example after analysing a large number of documents about the American government the phrase "The White" is most likely followed by "House."  Its not magic.  Its not thinking.  Its statistics or magic if you believe that matematics is magic.
+
+### Running AIA
+
+Executing the command:
+
+```shell
+aia
+```
+
+will prompt:
+
+```shell
+Please provide a prompt ID.
+```
+
+`AIA` requires a prompt ID to function. A prompt ID corresponds to the base name of a text file in your `prompts_dir` directory. To define your prompts directory, you can set an environment variable (`AIA_PROMPTS_DIR`) or specify the path directly as a command-line option.  To see all of the `AIA` command-line options do:
+
+```shell
+aia --help
+```
+
+### Set Up a Prompts Directory
+
+The easiest way to tell `AIA` where the prompts directory is located is using the system environment variable $AIA_PROMPTS_DIR
+
+```shell
+export AIA_PROMPTS_DIR=~/my_prompts
+mkdir $AIA_PROMPTS_DIR
+```
+
+## AIA Supports Parameterized Prompts
+
+`AIA`'s first layer of pre-compositional prompt management is parameterization -— where placeholders within a prompt are replaced with user-defined values. By default, `AIA` considers any uppercase sequence within square brackets as a placeholder.
+
+Examples of placeholders include:
+
+- `[KEYWORD]`
+- `[USER_ROLE]`
+- `[COMPUTER_LANGUAGE]`
+
+When using `AIA` with a sample prompt:
+
+```shell
+As a [ROLE], I want to [DO_SOMETHING].
+```
+
+`AIA` will ask for substitutions for each placeholder (keyword/parameter), saving your responses with the prompt file for future use. The last-used value for each placeholder is the default for subsequent uses of that specific prompt.
+
+### Create a Parameterized Prompt
+
+Let's create a simple yet flexible prompt file:
+
+```shell
+echo "[DO_WHAT]" > $AIA_PROMPTS_DIR/ad_hoc.txt
+```
+
+The associated "Prompt ID" is "ad_hoc" -— the basename of the file sans the ".txt" extension. Using the "ad_hoc" prompt ID:
+
+```shell
+aia ad_hoc
+```
+
+results in an interaction to specify a value for `[DO_WHAT]`. For instance, entering "tell me a joke" to replace "[DO_WHAT]" will generate a response but whether its a funny joke or a dad joke is completely up to the electrons that controll the statistics of the LLM. :)
+
+### The Next Parts
+
+Subsequent sections in this series cover:
+
+- **Comments and Directives**: Lines starting with "#" are comments and ignored during processing. Lines starting with "//" are directives and are executed (e.g., "//config chat? = true" to set interactive chat mode for the prompt.)
+
+- **Shell Integration**: Access to system environment variables and dynamic shell commands using the `--shell` option.
+
+- **Embedded RuBy (ERB)**: For expert users, the option `--erb` allows Ruby code to be embedded in prompts (`<%= ruby_code %>`), offering unparalleled flexibility in prompt composition.  This is one way to embed current data into prompts for LLMs which do not have access to current real-time data.
+
+> A pre-compositional prompt essentially serves as a template that expands into a full prompt, which is then processed by a generative AI to yield a tailored response.
+>
+> To recap, a prompt ID corresponds to the basename of a text file in a prompts directory. The simplest way to inform `AIA` of your prompts directory is through the environment variable `$AIA_PROMPTS_DIR`. For a prompt ID `ad_hoc`, `AIA` will read the prompt from `$AIA_PROMPTS_DIR/ad_hoc.txt`.
+>
+> NOTE: If you're on MacOS or another system where file extensions aren't visible in the terminal by default, consider adjusting your system settings to display file extensions.
+
+## Comments
+
+AI prompts can be thought of as programs that an AI processes to generate responses. Sometimes you get the desired outcome, and other times you don't. Iteration often precedes success, and you may later forget the rationale behind your original construction. Non-processable comments serve as documentation.
+
+Comments can also shed light on the expected values for specific keywords or parameters.
+
+Both comments and prompt content are fully searchable.
+
+### Line Comments
+
+A line beginning with the `#` character is treated as a line comment and is disregarded during prompt processing. Line comments are useful for providing metadata such as the file path, prompt description, author, or other identifying details.
+
+Since line comments are searchable, they can also provide auxiliary context relevant to the prompt.
+
+Below is an example of a `multi_step` prompt file with line comments:
+
+```shell
+# ~/prompts/multi_step.txt
+# Description: A template for multi-step prompts
+
+# Provide the LLM with the response format
+[STEP_1]
+
+# Define the role for the LLM
+[STEP_2]
+
+# Specify the task for the LLM
+[STEP_3]
+```
+
+### End of File Block Comment
+
+For content that doesn't fit into line comments, an end-of-file (EOF) comment block can be denoted as follows:
+
+```shell
+__END__
+```
+
+This indicates to `AIA` that no more prompt text follows.
+
+Example EOF block comment in a prompt file:
+
+```shell
+Tell me some dad jokes.
+
+__END__
+
+1. I'm reading a book on anti-gravity. It's impossible to put down.
+2. Did you hear about the restaurant on the moon? Great food, but no atmosphere.
+3. What do you call fake spaghetti? An impasta.
+```
+
+## Directives
+
+A directive is a line-specific action within the context of a prompt. It begins with the characters `//`. Here's the basic syntax of a directive:
+
+```shell
+//directive parameters
+```
+
+There should be no space between the `//` and the directive name, which is followed by at least one space before its parameters.
+
+### The `config` Directive
+
+Directives commonly adjust the configuration settings of a prompt. For example, to enter an interactive chat session without always using the `--chat` option, include a directive in the prompt file, as seen in `$AIA_PROMPTS_DIR/chat.txt`:
+
+```shell
+//config chat? = true
+//config terse? = true
+
+[WHAT IS ON YOUR MIND]
+```
+
+The first directive simulates the `--chat` command line option, while the second imitates `--terse`.
+
+To start a chat session using this prompt, simply execute:
+
+```shell
+aia chat
+```
+
+You can modify any configuration items in a prompt, including the AI model, the response's output file, or the fine-tuned control parameters like temperature and `topp`.  Its also possible to direct the prompt to a backend processor other than the default.  (Current `AIA` supports two backend processors `mods` and `sgpt`.  `mods` is the default because of its significant flexibility.)
+
+Additional directive commands were introduced in `AIA` v0.4.1, but might be deprecated due to the integration of embedded shell commands and Ruby sequences.
+
+### Parameter Substitution in Directives
+
+As discussed in Part 1, parameters in prompts are interchangeable. This is also true for directives:
+
+```shell
+//config terse? = [TERSE_YES_OR_NO]
+```
+
+While one could opt to use the `--terse` command line toggle directly, employing a directive allows the prompt to adapt between verbosity levels.
+
+Parameter substitutions apply uniformly to directives, just like any other part of the prompt.
+
+## Shell Integration
+
+The `--shell` option permits shell integration, facilitating access to system environment variables (envars) and the execution of embedded shell commands within prompts.
+
+### Accessing System Environment Variables
+
+Incorporating envars within prompts is somewhat akin to parameter usage. With parameters, however, users are asked to provide the values for substitution. Conversely, when an envar is used, its value is automatically fetched from the shell and embedded.
+
+Envars may be indicated by one of two patterns:
+
+- `$UPPERCASE_WORD`
+- `${UPPERCASE_WORD}`
+
+For instance, consider the following prompts:
+
+```shell
+As a $ROLE ...
+```
+
+versus
+
+```shell
+As a [ROLE] ...
+```
+
+In the first example, the shell supplies the `$ROLE` value, whereas the second prompt implies interaction with the user to define `[ROLE]`.
+
+In scenarios where multiple prompts utilize the same `ROLE`, it is practical to set an envar to circumvent the interactive step:
+
+```shell
+export ROLE="expert Ruby on Rails software developer"
+aia example1 --shell -o response1.md
+aia example2 --shell -o response2.md
+# ...
+```
+
+#### Contextual System Environment Variables
+
+With tools like `direnv`, you can set environment variables specific to your current directory tree context. On MacOS, `direnv` can be installed via `brew install direnv`.  There value only exists so long as you are working with the directory tree covered by the `.envrc` file the `direnv` uses to define its envars.
+
+Imagine working in two project directory trees with different roles. In a `src` directory, your role is that of a software developer, whereas in a `doc` directory, you perform as a documentation specialist.
+
+For the `src` directory, your `.envrc` file could be:
+
+```shell
+export ROLE="Crystal software developer"
+```
+
+Meanwhile, within the `doc` directory, `.envrc` might contain:
+
+```shell
+export ROLE="editorial assistant with experience writing documentation"
+```
+
+Now, consider this prompt, suitable for use in both contexts:
+
+```shell
+# ~/.prompts/review.txt
+
+As a $ROLE, review the following file and suggest improvements.
+```
+
+Depending on the active directory, invoking the prompt in `src` yields suggestions tailored for Crystal source code, whereas in `doc`, it provides advice based on markdown-formatted documentation.
+
+### Invoking Shell Commands
+
+Additionally, the `--shell` option enables `AIA` to execute shell commands embedded in the prompt. The result of the shell command is then injected directly into the spot where the command is placed in the text file.
+
+Here's the pattern for embedding a shell command:
+
+```shell
+$(...)
+```
+
+Whatever lies between the parentheses is executed as a shell command, ranging from the straightforward to the complex, depending on the desired outcome. Any output directed to `STDOUT` will be incorporated into the prompt text where specified.
+
+For a practical example, consider this prompt which is intended for scrutinizing a system log file:
+
+```shell
+# ~/.prompts/summarize_log.txt
+# Description: Examine a system log file for issues
+
+As an experienced system administrator and senior DevOps engineer on the $(uname -v) platform, please review the following log entries and summarize any potential issues, providing recommendations for mitigation: $(tail -n $LOG_ENTRIES $LOG_FILE)
+```
+
+
+
+> A pre-compositional prompt serves as a foundational template. It's expanded into a fully-fledged prompt, ready to be handed off to a generative AI processor. The end goal is a response tailored to your specific requirements.
+
+
+## Harnessing Ruby's Capabilities
+
+The `AIA` command-line option `--erb` ebables the execution of embedded Ruby code within a prompt text file.
+
+Ruby ERB (Embedded Ruby) is a system designed for interweaving Ruby code with text documents. This is especially useful for content that requires dynamic generation such as text files that undergo computation or data incorporation. 
+
+ERB boasts numerous powerful features:
+
+1. **Ruby Code Embedding**: Insert and execute any valid Ruby code inside a text document. Whether it's performing calculations or invoking methods, ERB's capabilities are far-reaching.
+
+2. **Safe Evaluation**: ERB templates can be evaluated within a `binding` that exposes only select variables and methods. This precaution is crucial when dealing with untrusted template content.
+
+3. **Control Structures**: Adopt Ruby control structures such as loops and conditionals within ERB, allowing conditional content inclusion.
+
+4. **User-Friendly**: The ERB syntax is straightforward and blends seamlessly with usual text, providing a smooth experience for those familiar with HTML and similar languages.
+
+5. **Included in Ruby's Standard Library**: ERB comes bundled with Ruby, negating the need for extra installations where Ruby is present.
+
+6. **Industry Standard**: As the default engine for many Ruby frameworks, including Rails for views, ERB's reliability and support are well-established.
+
+7. **Error Reporting**: ERB pinpoints errors with detailed stack traces, pointing out the exact line in the template to facilitate debugging.
+
+8. **Commentary**: Integrate comments into an ERB template that remain hidden from the final output, parallel to Ruby comment syntax and the line comments used by `ai` which aids in documentation.
+
+### The Concept of Binding
+
+In Ruby — and ERB by extension — the 'binding' refers to the execution context, the sphere where Ruby objects bind to values. It's the scope within which Ruby objects are accessible; objects outside the binding remain out of reach.
+
+With the `--erb` option in `AIA`, the binding for Ruby code in a prompt text file is confined to the file itself. You can define anything from scalar values to arrays and hashes, as well as methods or any other Ruby object type you might need. There is great freedom, yet the binding keeps a firm boundary — if an object is undefined within the prompt text, it remains inaccessible.
+
+For a detailed exploration of the ERB syntax, refer to [this comprehensive guide](https://www.puppet.com/docs/puppet/latest/lang_template_erb.html).
+
+### ERB Syntax at a Glance
+
+Ruby code embedding with ERB offers two main patterns:
+
+- `<% ruby code %>` for code execution only.
+- `<%= ruby code %>` for code execution with output.
+
+Both patterns support multi-line Ruby code; you're not constrained to a single line. 
+
+Using the first pattern, `<% ... %>`, you define Ruby objects within the binding — setting variable values, declaring methods, and so forth — without generating any output to the prompt text.  After execution the ERB block is removed from the prompt text.
+
+The second pattern, `<%= ... %>`, includes an equals sign '=' that signals the output of the ERB block to be inserted into the prompt text.  Like the first, the ERB block is removed but its output remains as part of the prompt text.
+
+```ruby
+<$ name = "Ruby" %>
+Say hello to <%= name %> in three different languages.
+```
+
+In the first line the Ruby variable `name` was added to the binding as a Sring type with the value of "Ruby" so that in the second line the value of that variable could be accessed as used within the prompt text.
+
+
+### Conditional Logic
+
+ERB empowers you to create conditional prompts based on the available binding.
+
+```ruby
+<% "Ruby" == name %>
+  Review these files: $(ls -1 *.rb) for duplicate code blocks.
+M% else %>
+  Review the grammar and spelling in these files $(ls -1 *.md)
+<% end %>
+```
+
+### Accessing Current Data
+
+By nature, large language models (LLMs) have a historical cut-off for training data. Only recently, generative AI tools granting real-time data access have been introduced. With ERB, you can complement LLM data by integrating up-to-date information directly into your prompts.
+
+```ruby
+<%
+  require 'alphavantagerb'
+  stock_info      = Alphavantage::Stock.new(
+                      symbol: 'AAPL', 
+                      key:    "your api key").quote
+  current_price   = stock_info.price
+  change          = stock_info.change
+  change_percent  = stock_info.change_percent
+%>
+
+The latest stock information for Apple Inc. (AAPL) is as follows:
+- Current Price: <%= current_price %>
+- Change: <%= change %>
+- Change (%): <%= change_percent %>
+
+Generate a brief analysis of the stock performance based on this information.
+```
+
+This script illustrates how the ERB binding can extend to include external Ruby objects, though external libraries must be explicitly required within the ERB's binding.
+
+## Summary of AIA Command-Line Tool
+
+The AIA tool is a command-line interface designed to enable users to interact with an AI assistant, specifically with an AI model backend. It allows users to submit prompts, load context for AI processing, and receive responses from the AI model. The CLI tool is versatile and offers a range of options and configurations.
+
+Key features of the AIA tool based on the user manual:
+
+- **Command Syntax**: `aia [options]* PROMPT_ID [CONTEXT_FILE]* [-- EXTERNAL_OPTIONS+]`
+- **Core Function**: Sends prompts to and receives responses from an AI backend.
+- **Prompt ID**: A required argument that identifies the prompt to be processed.
+- **Context Files**: Optional files that provide additional context for prompt processing.
+- **External Options**: Additional backend-specific options can be passed after " -- ".
+
+**Options Available**:
+- Chat sessions (`--chat`) and turning off standard output for backend-only interaction.
+- Shell completion scripts for various shell types (`--completion`).
+- Configuration dumping (`--dump`).
+- Environment variable substitution (`--shell`) and embedded Ruby execution (`--erb`).
+- Model name specification (`--model`), and text-to-speech output (`--speak`).
+- Terse response directive (`--terse`), checking for updates (`--version`), and backend specification (`-b`).
+- Config files loading (`-c`), debugging mode activation (`-d`), prompt file editing (`-e`).
+- Fuzzy matching for prompts search (`-f`), help display (`-h`), logging (`-l`).
+- Markdown formatting (`-m`), output file specification (`-o`), and prompt directory setting (`-p`).
+- Role ID to configure the AI's approach (`-r`), verbose output (`-v`).
+
+**Configuration Hierarchy**:
+- Environment variables prefixed with "AIA_" can alter default settings.
+- Command-line options have precedence over environment variables.
+- Config file settings and prompt directives within files can override other configurations.
+
+**OpenAI Account Requirement**:
+- Users must have an OpenAI access token specified through environment variables (`OPENAI_ACCESS_TOKEN` or `OPENAI_API_KEY`).
+
+**Usage and Integration**:
+- The tool is designed to be flexible, with the ability to customize output behavior and integrate auto-completion scripts into the shell environment.
+- Configuration formats like YAML and TOML can be outputted using `--dump`.
+
+**Prompt Directives**:
+- Lines beginning with "//" in a prompt text file serve as directives, influencing behavior and configurations.
+
+**Additional Information and Third-Party Tools**:
+- The manual references additional documentation for OpenAI token access, as well as third-party CLI tools like `mods` and `sgpt` that integrate with AI services.
+
+Through this tool, users have the ability to create highly customized interactions with an AI backend, using a command-line environment for efficient and programmable access to AI processing capabilities.
+

data/justfile

@@ -69,6 +69,11 @@ project     := "`basename $RR`"
   backup_envrc.rb
 
 
+# Delete all mods saved conversations
+mods_delete_all:
+  mods -l | awk '{print $1}' | xargs -I {} mods -d {}
+
+
 #################################################
 ## Private recipes
 
@@ -109,11 +114,26 @@ module_gem := "/Users/dewayne/sandbox/git_repos/gem.just"
 module_version := "/Users/dewayne/just_modules/version.just"
 
 
+# Install Locally
+install: update_toc_in_readmen create_man_page test
+  rake install
+
+
+# Create the TOC
+update_toc_in_readmen:
+  rake toc
+
+
 # Preview man page
 preview_man_page:
   kramdown-man {{RR}}/man/aia.1.md
 
 
+# Run Unit Tests
+test:
+  rake test
+  
+
 # View man page
 view_man_page: create_man_page
   man {{RR}}/man/aia.1

data/lib/aia/aia_completion.bash

@@ -3,7 +3,7 @@
 # the bash shell
 #
 # This script assumes that the system environment
-# variable PROMPTS_DIR has been set correctly
+# variable AIA_PROMPTS_DIR has been set correctly
 
 _aia_completion() {
   # The current word being completed
@@ -18,7 +18,7 @@ _aia_completion() {
   # Check if we are currently completing the option that requires prompt IDs
   if [[ "$prev_word" == "aia" ]]; then
     # Change directory to the prompts directory
-    cd "$PROMPTS_DIR" || return
+    cd "$AIA_PROMPTS_DIR" || return
 
     # Generate a list of relative paths from the ~/.prompts directory (without .txt extension)
     local files=($(find . -name "*.txt" -type f | sed 's|^\./||' | sed 's/\.txt$//'))

data/lib/aia/aia_completion.fish

@@ -2,7 +2,7 @@
 # Setup a prompt completion for use with the fish shell
 #
 # This script assumes that the system environment
-# variable PROMPTS_DIR has been set correctly
+# variable AIA_PROMPTS_DIR has been set correctly
 
 function __fish_aia_complete
   # Get the command line and current token
@@ -12,9 +12,9 @@ function __fish_aia_complete
   # Check if we are currently completing the option that requires prompt IDs
   if set -q cmd_line[2]
     # Change directory to the prompts directory
-    if test -d $PROMPTS_DIR
-      pushd $PROMPTS_DIR
-      # Generate completions based on .txt files in the PROMPTS_DIR directory
+    if test -d $AIA_PROMPTS_DIR
+      pushd $AIA_PROMPTS_DIR
+      # Generate completions based on .txt files in the AIA_PROMPTS_DIR directory
       for file in (find . -name "*.txt" -type f)
         set file (string replace -r '\.txt$' '' -- $file)
         set file (string replace -r '^\./' '' -- $file)

data/lib/aia/aia_completion.zsh

@@ -3,7 +3,7 @@
 # the zsh shell
 #
 # This script assumes that the system environment
-# variable PROMPTS_DIR has been set correctly
+# variable AIA_PROMPTS_DIR has been set correctly
 
 _aia_completion() {
   # The current word being completed
@@ -18,7 +18,7 @@ _aia_completion() {
   # Check if we are currently completing the option that requires prompt IDs
   if [[ "$prev_word" == "aia" ]]; then
     # Change directory to the prompts directory
-    cd "$PROMPTS_DIR" || return
+    cd "$AIA_PROMPTS_DIR" || return
 
     # Generate a list of relative paths from the ~/.prompts directory (without .txt extension)
     local files=($(find . -name "*.txt" -type f | sed 's|^\./||' | sed 's/\.txt$//'))

data/lib/aia/cli.rb

@@ -126,7 +126,7 @@ class AIA::Cli
       completion: [nil,       "--completion"],
       #
       edit?:      [false,     "-e --edit"],
-      env?:       [false,     "--env"],
+      shell?:     [false,     "--shell"],
       erb?:       [false,     "--erb"],
       debug?:     [false,     "-d --debug"],
       verbose?:   [false,     "-v --verbose"],
@@ -140,10 +140,10 @@ class AIA::Cli
       #
       role:       ['',        "-r --role"],
       #
-      config_file:[nil,                       "-c --config"],
+      config_file:[nil,                       "-c --config_file"],
       prompts_dir:["~/.prompts",              "-p --prompts"],
-      output_file:["temp.md",                 "-o --output --no-output"],
-      log_file:   ["~/.prompts/_prompts.log", "-l --log --no-log"],
+      out_file:   [STDOUT,                    "-o --out_file --no-out_file"],
+      log_file:   ["~/.prompts/_prompts.log", "-l --log_file --no-log_file"],
       #
       backend:    ['mods',    "-b --be --backend --no-backend"],
     }
@@ -236,7 +236,7 @@ class AIA::Cli
           arguments.slice!(index,1)
         else
           if switch.include?('-no-')
-            AIA.config[option_sym] = switch.include?('output') ? STDOUT : nil
+            AIA.config[option_sym] = switch.include?('out_file') ? STDOUT : nil
             arguments.slice!(index,1)
           else
             AIA.config[option_sym] = arguments[index + 1]

data/lib/aia/directives.rb

@@ -36,10 +36,6 @@ class AIA::Directives
   end
 
 
-  def shell(what) = puts `#{what}`
-  def ruby(what)  = eval what
-
-
   # Allows a prompt to change its configuration environment
   def config(what)
     parts = what.split(' ')

data/lib/aia/main.rb

@@ -21,6 +21,12 @@ class AIA::Main
 
     AIA::Cli.new(args)
 
+    if AIA.config.debug?
+      debug_me('== CONFIG AFTER CLI =='){[
+        "AIA.config"
+      ]}
+    end
+
     @logger = AIA::Logging.new(AIA.config.log_file)
 
     @logger.info(AIA.config) if AIA.config.debug? || AIA.config.verbose?
@@ -62,7 +68,7 @@ class AIA::Main
     @engine.execute_my_directives
 
     if AIA.config.chat?
-      AIA.config.output_file = STDOUT 
+      AIA.config.out_file = STDOUT 
       AIA.config.extra = "--quiet" if 'mods' == AIA.config.backend
     end
 
@@ -103,7 +109,7 @@ class AIA::Main
 
     result  = backend.run
 
-    AIA.config.output_file.write result
+    AIA.config.out_file.write result
 
     logger.prompt_result(@prompt, result)
 

data/lib/aia/prompt.rb

@@ -12,9 +12,9 @@ class AIA::Prompt
   class Fake
     def id          = '_fake_'
     def path        = '_fake_'
+    def text        = ''
     def keywords    = []
     def directives  = []
-    def text        = ''
     def to_s        = ''
   end
 
@@ -42,7 +42,7 @@ class AIA::Prompt
 
     if build
       @prompt.text = render_erb(@prompt.text)   if AIA.config.erb?
-      @prompt.text = replace_env(@prompt.text)  if AIA.config.env?
+      @prompt.text = replace_env(@prompt.text)  if AIA.config.shell?
       process_prompt 
     end
   end
@@ -231,7 +231,7 @@ class AIA::Prompt
       "--header-first",
       "--prompt='Search term: '",
       '--delimiter :',
-      "--preview 'cat $PROMPTS_DIR/{1}.txt'",
+      "--preview 'cat #{AIA.config.prompts_dir}/{1}.txt'",
       "--preview-window=down:50%:wrap"
     ].join(' ') 
 

data/lib/aia/tools/mods.rb

@@ -26,6 +26,7 @@ class AIA::Mods < AIA::Tools
     http-proxy 
     max-retries
     max-tokens 
+    model
     no-cache
     no-limit  
     quiet      

data/lib/aia.rb

@@ -1,7 +1,23 @@
 # lib/aia.rb
 
-require 'debug_me'
-include DebugMe
+def tramp_require(what, &block)
+  loaded, require_result = false, nil
+
+  begin
+    require_result = require what
+    loaded = true
+  rescue Exception => ex
+    # Do nothing
+  end
+
+  yield if loaded and block_given?
+
+  require_result
+end
+
+tramp_require('debug_me') {
+  include DebugMe
+}
 
 require 'hashie'
 require 'pathname'

data/main.just

@@ -16,11 +16,26 @@ module gem /Users/dewayne/sandbox/git_repos/gem.just
 module version /Users/dewayne/just_modules/version.just
 
 
+# Install Locally
+install: update_toc_in_readmen create_man_page test
+  rake install
+
+
+# Create the TOC
+update_toc_in_readmen:
+  rake toc
+
+
 # Preview man page
 preview_man_page:
   kramdown-man {{RR}}/man/aia.1.md
 
 
+# Run Unit Tests
+test:
+  rake test
+  
+
 # View man page
 view_man_page: create_man_page
   man {{RR}}/man/aia.1

data/man/aia.1

@@ -23,7 +23,7 @@ External options are optional\.  Anything that follow \[lq] \-\- \[lq] will be s
 .SH OPTIONS
 .TP
 \fB\-\-chat\fR
-begin a chat session with the backend after the initial prompt response;  will set \-\-no\-output so that the backend response comes to STDOUT\.
+begin a chat session with the backend after the initial prompt response;  will set \-\-no\-out\[ru]file so that the backend response comes to STDOUT\.
 .TP
 \fB\-\-completion\fR \fISHELL\[ru]NAME\fP
 .TP
@@ -32,7 +32,7 @@ begin a chat session with the backend after the initial prompt response;  will s
 \fB\-e\fR, \fB\-\-edit\fR
 Invokes an editor on the prompt file\.  You can make changes to the prompt file, save it and the newly saved prompt will be processed by the backend\.
 .TP
-\fB\-\-env\fR
+\fB\-\-shell\fR
 This option tells \fBaia\fR to replace references to system environment variables in the prompt with the value of the envar\.  envars are like \[Do]HOME and \[Do]\[lC]HOME\[rC] in this example their occurance will be replaced by the value of ENV\[lB]\[oq]HOME\[cq]\[rB]\.  Also the dynamic shell command in the pattern \[Do](shell command) will be executed and its output replaces its pattern\.  It does not matter if your shell uses different patters than BASH since the replacement is being done within a Ruby context\.
 .TP
 \fB\-\-erb\fR
@@ -53,7 +53,7 @@ Print Version \- default is false
 \fB\-b\fR, \fB\-\-\[lB]no\[rB]\-backend\fR \fILLM TOOL\fP
 Specify the backend prompt resolver \- default is mods
 .TP
-\fB\-c\fR, \fB\-\-config\fR \fIPATH\[ru]TO\[ru]CONFIG\[ru]FILE\fP
+\fB\-c\fR, \fB\-\-config\[ru]file\fR \fIPATH\[ru]TO\[ru]CONFIG\[ru]FILE\fP
 Load Config File \- default is nil
 .TP
 \fB\-d\fR, \fB\-\-debug\fR
@@ -68,13 +68,13 @@ Use Fuzzy Matching when searching for a prompt \- default is false
 \fB\-h\fR, \fB\-\-help\fR
 Show Usage \- default is false
 .TP
-\fB\-l\fR, \fB\-\-\[lB]no\[rB]\-log\fR \fIPATH\[ru]TO\[ru]LOG\[ru]FILE\fP
+\fB\-l\fR, \fB\-\-\[lB]no\[rB]\-log\[ru]file\fR \fIPATH\[ru]TO\[ru]LOG\[ru]FILE\fP
 Log FILEPATH \- default is \[Do]HOME\[sl]\.prompts\[sl]prompts\.log
 .TP
 \fB\-m\fR, \fB\-\-\[lB]no\[rB]\-markdown\fR
 Format with Markdown \- default is true
 .TP
-\fB\-o\fR, \fB\-\-\[lB]no\[rB]\-output\fR \fIPATH\[ru]TO\[ru]OUTPUT\[ru]FILE\fP
+\fB\-o\fR, \fB\-\-\[lB]no\[rB]\-out\[ru]file\fR \fIPATH\[ru]TO\[ru]OUTPUT\[ru]FILE\fP
 Out FILENAME \- default is \.\[sl]temp\.md
 .TP
 \fB\-p\fR, \fB\-\-prompts\fR \fIPATH\[ru]TO\[ru]DIRECTORY\fP
@@ -109,7 +109,7 @@ Currently there is not specific standard for name of the OpenAI key\.  Some prog
 To acquire an OpenAI access key, first create an account on the OpenAI platform, where further documentation is available\.
 .SH USAGE NOTES
 .PP
-\fBaia\fR is designed for flexibility, allowing users to pass prompt ids and context files as arguments\. Some options change the behavior of the output, such as \fB\-\-output\fR for specifying a file or \fB\-\-no\-output\fR for disabling file output in favor of standard output (STDPIT)\.
+\fBaia\fR is designed for flexibility, allowing users to pass prompt ids and context files as arguments\. Some options change the behavior of the output, such as \fB\-\-out\[ru]file\fR for specifying a file or \fB\-\-no\-out\[ru]file\fR for disabling file output in favor of standard output (STDPIT)\.
 .PP
 The \fB\-\-completion\fR option displays a script that enables prompt ID auto\-completion for bash, zsh, or fish shells\. It\[cq]s crucial to integrate the script into the shell\[cq]s runtime to take effect\.
 .PP

data/man/aia.1.md

@@ -26,7 +26,7 @@ The aia command-line tool is an interface for interacting with an AI model backe
 ## OPTIONS
 
 `--chat`
-: begin a chat session with the backend after the initial prompt response;  will set --no-output so that the backend response comes to STDOUT.
+: begin a chat session with the backend after the initial prompt response;  will set --no-out_file so that the backend response comes to STDOUT.
 
 `--completion` *SHELL_NAME*
 : Show completion script for bash|zsh|fish - default is nil
@@ -37,7 +37,7 @@ The aia command-line tool is an interface for interacting with an AI model backe
 `-e`, `--edit`
 : Invokes an editor on the prompt file.  You can make changes to the prompt file, save it and the newly saved prompt will be processed by the backend.
 
-`--env`
+`--shell`
 : This option tells `aia` to replace references to system environment variables in the prompt with the value of the envar.  envars are like $HOME and ${HOME} in this example their occurance will be replaced by the value of ENV['HOME'].  Also the dynamic shell command in the pattern $(shell command) will be executed and its output replaces its pattern.  It does not matter if your shell uses different patters than BASH since the replacement is being done within a Ruby context.
 
 `--erb`
@@ -58,7 +58,7 @@ The aia command-line tool is an interface for interacting with an AI model backe
 `-b`, `--[no]-backend` *LLM TOOL*
 : Specify the backend prompt resolver - default is mods
 
-`-c`, `--config` *PATH_TO_CONFIG_FILE*
+`-c`, `--config_file` *PATH_TO_CONFIG_FILE*
 : Load Config File - default is nil
 
 `-d`, `--debug`
@@ -73,13 +73,13 @@ The aia command-line tool is an interface for interacting with an AI model backe
 `-h`, `--help`
 : Show Usage - default is false
 
-`-l`, `--[no]-log` *PATH_TO_LOG_FILE*
+`-l`, `--[no]-log_file` *PATH_TO_LOG_FILE*
 : Log FILEPATH - default is $HOME/.prompts/prompts.log
 
 `-m`, `--[no]-markdown`
 : Format with Markdown - default is true
 
-`-o`, `--[no]-output` *PATH_TO_OUTPUT_FILE*
+`-o`, `--[no]-out_file` *PATH_TO_OUTPUT_FILE*
 : Out FILENAME - default is ./temp.md
 
 `-p`, `--prompts` *PATH_TO_DIRECTORY*
@@ -115,7 +115,7 @@ To acquire an OpenAI access key, first create an account on the OpenAI platform,
 
 ## USAGE NOTES
 
-`aia` is designed for flexibility, allowing users to pass prompt ids and context files as arguments. Some options change the behavior of the output, such as `--output` for specifying a file or `--no-output` for disabling file output in favor of standard output (STDPIT).
+`aia` is designed for flexibility, allowing users to pass prompt ids and context files as arguments. Some options change the behavior of the output, such as `--out_file` for specifying a file or `--no-out_file` for disabling file output in favor of standard output (STDPIT).
 
 The `--completion` option displays a script that enables prompt ID auto-completion for bash, zsh, or fish shells. It's crucial to integrate the script into the shell's runtime to take effect.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aia
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-01 00:00:00.000000000 Z
+date: 2024-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -177,6 +177,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".config/tocer/configuration.yml"
 - ".envrc"
 - ".semver"
 - CHANGELOG.md
@@ -185,6 +186,7 @@ files:
 - README.md
 - Rakefile
 - bin/aia
+- doc/aia_and_pre_compositional_prompts.md
 - justfile
 - lib/aia.rb
 - lib/aia/aia_completion.bash
@@ -231,7 +233,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: AI Assistant (aia) a command-line (CLI) utility