aia 0.3.20 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3061141e7330122b3ec6ffd64cf967d8fb0c4f8741531337bf32bfba28ee4ea
-  data.tar.gz: b62080a48b5d4afefb9da0eb5bdc1deff20a8c666048a755b38f759815bea8f3
+  metadata.gz: 24e36e9066b83229df951d172cfb3fd7185cadb433fd992ab37fede8d45b8ea5
+  data.tar.gz: f7ce893975dfb29dd69d1ec0922f8ea30987f88d1d3dd69f0ca877218c6c54fc
 SHA512:
-  metadata.gz: c2e83d7db907fe2e3c91aae7acad12bf1569071479f99ba70f3626c98640323148e83b46cda2aa2353afcad54d740116999399e8e646b7db02b4a7e42916d0fc
-  data.tar.gz: 3f327c042a67a574231d9e25a5ed8df83ca6d4cf28444ae92be20d241480143ce95ec4e4238aab70caecf0c9c64417d579c6e8fd3dd3e7928c64f8e56fb2196a
+  metadata.gz: 0172e7c82b9e346d176df7691e5eb422515e25f4f7ed243cb92cd38419a4e8a18a1df9f5500ac0606c6bb30d48e88662237877aee4667aedf9cd02973a190268
+  data.tar.gz: c826c22f5b1789ffeeca7982860764527350d3b352cb428a4b1cc6ccc63025fa1c4347ed098477d8d6a0f2f63dfe8fc8187eb9570096698487bf69fe6f8903c0

data/.semver

@@ -1,6 +1,6 @@
 ---
 :major: 0
-:minor: 3
-:patch: 20
+:minor: 4
+:patch: 2
 :special: ''
 :metadata: ''

data/CHANGELOG.md

@@ -1,4 +1,12 @@
 ## [Unreleased]
+## [0.4.2] 2023-12-31
+- added the --role CLI option to pre-pend a "role" prompt to the front of a primary prompt.
+
+## [0.4.1] 2023-12-31
+- added a chat mode
+- prompt directives now supported
+- version bumped to match the `prompt_manager` gem
+
 ## [0.3.20] 2023-12-28
 - added work around to issue with multiple context files going to the `mods` backend
 - added shellwords gem to santize prompt text on the command line

data/README.md

@@ -6,7 +6,8 @@ Uses the gem "prompt_manager" to manage the prompts sent to the `mods` command-l
 
 **Most Recent Change**
 
-v0.3.19 - Major code refactoring.  Now supports conf giles in YAML or TOML format.  Supports system environment variable (envar) over-rides of default config values using envar's with keys that have the prefix "AIA_" followed by a config item name in all upper case.
+v0.4.2 = Added a role option to be prepended to a primary prompt.
+v0.4.1 - Added a chat mode.  Prompt directives are now supported.
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -15,8 +16,12 @@ v0.3.19 - Major code refactoring.  Now supports conf giles in YAML or TOML forma
   - [Installation](#installation)
   - [Usage](#usage)
   - [System Environment Variables (envar)](#system-environment-variables-envar)
+  - [Prompt Directives](#prompt-directives)
+  - [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)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
@@ -37,13 +42,14 @@ Install the command-line utilities by executing:
 
 You will also need to establish a directory in your file system where your prompt text files, last used parameters and usage log files are kept.
 
-Setup a system environment variable named "PROMPTS_DIR" that points to your prompts directory.  The default is in your HOME directory named ".prompts_dir"
+Setup a system environment variable named "AIA_PROMPTS_DIR" that points to your prompts directory.  The default is in your HOME directory named ".prompts_dir"
 
-You will also need to source the completion script.
+You may also want to install the completion script for your shell.  To get a copy of the completion script do:
 
-TODO: May want to add a `setup` function to the command-line options that will create the directory, and do something with the completion function.
+`aia --completion bash`
+
+`fish` and `zsh` are also available.
 
-TODO: don't forget to mention have access token (API keys) setup as envars for the various backend services like OpenAI... if they are still in business.
 
 ## Usage
 
@@ -52,7 +58,7 @@ The usage report obtained using either `-h` or `--help` is implemented as a stan
 ```text
 $ aia --help
 
-aia(1)                           User Manuals                           aia(1)
+aia(1)                                   User Manuals                                  aia(1)
 
 NAME
        aia - command-line interface for an AI assistant
@@ -61,157 +67,171 @@ SYNOPSIS
        aia [options]* PROMPT_ID [CONTEXT_FILE]* [-- EXTERNAL_OPTIONS+]
 
 DESCRIPTION
-       The aia command-line tool is an interface for interacting with an AI
-       model backend, providing a simple way to send prompts and receive
-       responses. The CLI supports various options to customize the
-       interaction, load a configuration file, edit prompts, set debugging
-       levels, and more.
+       The aia command-line tool is an interface for interacting with an AI model backend,
+       providing a simple way to send prompts and receive responses. The CLI supports various
+       options to customize the interaction, load a configuration file, edit prompts, set
+       debugging levels, and more.
 
 ARGUMENTS
        PROMPT_ID
               This is a required argument.
 
        CONTEXT_FILES
-              This is an optional argument.  One or more files can be added to
-              the prompt as context for the backend gen-AI tool to process.
+              This is an optional argument.  One or more files can be added to the prompt as
+              context for the backend gen-AI tool to process.
 
        EXTERNAL_OPTIONS
-              External options are optional.  Anything that follow “ -- “ will
-              be sent to the backend gen-AI tool.  For example “-- -C -m
-              gpt4-128k” will send the options “-C -m gpt4-128k” to the
-              backend gen-AI tool.  aia will not validate these external
-              options before sending them to the backend gen-AI tool.
+              External options are optional.  Anything that follow “ -- “ will be sent to the
+              backend gen-AI tool.  For example “-- -C -m gpt4-128k” will send the options
+              “-C -m gpt4-128k” to the backend gen-AI tool.  aia will not validate these
+              external options before sending them to the backend gen-AI tool.
 
 OPTIONS
-       -c, --config PATH_TO_CONFIG_FILE
-              Load Config File - default: nil
+       --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.
+
+       --completion SHELL_NAME
 
        --dump FORMAT
 
-       -e, --edit
-              Edit the Prompt File - default: false
+       --model NAME
+              Name of the LLM model to use - default is gpt-4-1106-preview
 
-       -d, --debug
-              Turn On Debugging - default: false
+       --speak
+              Simple implementation. Uses the “say” command to speak the response.  Fun with
+              --chat
 
-       -v, --verbose
-              Be Verbose - default: false
+       --terse
+              Add a clause to the prompt text that instructs the backend to be terse in its
+              response.
 
        --version
-              Print Version - default: false
+              Print Version - default is false
 
-       -h, --help
-              Show Usage - default: false
+       -b, --[no]-backend LLM TOOL
+              Specify the backend prompt resolver - default is mods
 
-       -s, --search TERM
-              Search for prompts contain TERM - default: nil
+       -c, --config PATH_TO_CONFIG_FILE
+              Load Config File - default is nil
 
-       -f, --fuzzy`
-              Use Fuzzy Matching when searching for a prompt - default: false
+       -d, --debug
+              Turn On Debugging - default is false
 
-       --completion SHELL_NAME
+       -e, --edit
+              Edit the Prompt File - default is false
 
-       -o, --[no]-output PATH_TO_OUTPUT_FILE
-              Out FILENAME - default: ./temp.md
+       -f, --fuzzy`
+              Use Fuzzy Matching when searching for a prompt - default is false
+
+       -h, --help
+              Show Usage - default is false
 
        -l, --[no]-log PATH_TO_LOG_FILE
-              Log FILEPATH - default: $HOME/.prompts/prompts.log
+              Log FILEPATH - default is $HOME/.prompts/prompts.log
 
        -m, --[no]-markdown
-              Format with Markdown - default: true
+              Format with Markdown - default is true
 
-       --model NAME
-              Name of the LLM model to use - default: gpt-4-1106-preview
+       -o, --[no]-output PATH_TO_OUTPUT_FILE
+              Out FILENAME - default is ./temp.md
 
        -p, --prompts PATH_TO_DIRECTORY
-              Directory containing the prompt files - default: ~/.prompts
+              Directory containing the prompt files - default is ~/.prompts
 
-       -b, --[no]-backend LLM TOOL
-              Specify the backend prompt resolver - default: :mods
+       -r, --role ROLE_ID
+              A role ID is the same as a prompt ID.  A “role” is a specialized prompt that
+              gets pre-pended to another prompt.  It’s purpose is to configure the LLM into a
+              certain orientation within which to resolve its primary prompt.
 
-ENVIRONMENT
-       The aia CLI uses the following environment variables:
-
-              • AIA_PROMPTS_DIR: Path to the directory containing prompts
-                files - default: $HOME/.prompts_dir
-
-              • AIA_BACKEND: The AI command-line program used - default: mods
+       -v, --verbose
+              Be Verbose - default is false
 
-              • EDITOR: The text editor used by the edit option - default:
-                edit
+CONFIGURATION HIERARCHY
+       System Environment Variables (envars) that are all uppercase and begin with “AIA_” can
+       be used to over-ride the default configuration settings.  For example setting “export
+       AIA_PROMPTS_DIR=~/Documents/prompts” will over-ride the default configuration;
+       however, a config value provided by a command line options will over-ride an envar
+       setting.
 
-              • AIA_MODEL: The AI model specification - default:
-                gpt-4-1106-preview
+       Configuration values found in a config file will over-ride all other values set for a
+       config item.
 
-              • AIA_OUTPUT: The default filename for output - default:
-                ./temp.md
+       ”//config” directives found inside a prompt file over-rides that config item
+       regardless of where the value was set.
 
-              • AIA_PROMPT_LOG: The default filepath for the prompts log -
-                default: $HOME/.prompts/_prompts.log
+       For example “//config chat? = true” within a prompt will setup the chat back and forth
+       chat session for that specific prompt regardless of the command line options or the
+       envar AIA_CHAT settings
 
-       Additionally, the program requires an OpenAI access key, which can be
-       specified using one of the following environment variables:
+OpenAI ACCOUNT IS REQUIRED
+       Additionally, the program requires an OpenAI access key, which can be specified using
+       one of the following environment variables:
 
               • OPENAI_ACCESS_TOKEN
 
               • OPENAI_API_KEY
 
-       Currently there is not specific standard for name of the OpenAI key.
-       Some programs use one name, while others use a different name.  Both of
-       the envars listed above mean the same thing.  If you use more than one
-       tool to access OpenAI resources, you may have to set several envars to
-       the same key value.
+       Currently there is not specific standard for name of the OpenAI key.  Some programs
+       use one name, while others use a different name.  Both of the envars listed above mean
+       the same thing.  If you use more than one tool to access OpenAI resources, you may
+       have to set several envars to the same key value.
 
-       To acquire an OpenAI access key, first create an account on the OpenAI
-       platform, where further documentation is available.
+       To acquire an OpenAI access key, first create an account on the OpenAI platform, where
+       further documentation is available.
 
 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.
+       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).
+
+       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.
 
-       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.
+       The --dump options will send the current configuration to STDOUT in the format
+       requested.  Both YAML and TOML formats are supported.
+
+PROMPT DIRECTIVES
+       Within a prompt text file any line that begins with “//” is considered a prompt
+       directive.  There are numerious prompt directives available.  In the discussion above
+       on the configuration you learned about the “//config” directive.
+
+       Detail discussion on individual prompt directives is TBD.  Most likely it will be
+       handled in the github wiki <https://github.com/MadBomber/aia>
 
 SEE ALSO
 
-              • OpenAI Platform Documentation
-                <https://platform.openai.com/docs/overview>
+              • OpenAI Platform Documentation <https://platform.openai.com/docs/overview>
                  for more information on obtaining access tokens
                 <https://platform.openai.com/account/api-keys>
                  and working with OpenAI models.
 
               • mods <https://github.com/charmbracelet/mods>
-                 for more information on mods - AI for the command line, built
-                for pipelines.  LLM based AI is really good at interpreting
-                the output of commands and returning the results in CLI
-                friendly text formats like Markdown. Mods is a simple tool
-                that makes it super easy to use AI on the command line and in
+                 for more information on mods - AI for the command line, built for pipelines.
+                LLM based AI is really good at interpreting the output of commands and
+                returning the results in CLI friendly text formats like Markdown. Mods is a
+                simple tool that makes it super easy to use AI on the command line and in
                 your pipelines. Mods works with OpenAI
                 <https://platform.openai.com/account/api-keys>
                  and LocalAI <https://github.com/go-skynet/LocalAI>
 
               • sgpt <https://github.com/tbckr/sgpt>
-                 (aka shell-gpt) is a powerful command-line interface (CLI)
-                tool designed for seamless interaction with OpenAI models
-                directly from your terminal. Effortlessly run queries,
-                generate shell commands or code, create images from text, and
-                more, using simple commands. Streamline your workflow and
-                enhance productivity with this powerful and user-friendly CLI
-                tool.
+                 (aka shell-gpt) is a powerful command-line interface (CLI) tool designed for
+                seamless interaction with OpenAI models directly from your terminal.
+                Effortlessly run queries, generate shell commands or code, create images from
+                text, and more, using simple commands. Streamline your workflow and enhance
+                productivity with this powerful and user-friendly CLI tool.
 
 AUTHOR
        Dewayne VanHoozer <dvanhoozer@gmail.com>
 
-AIA                               2024-01-01                            aia(1)
-
+AIA                                       2024-01-01                                   aia(1)
 ```
 
 ## System Environment Variables (envar)
 
-The `aia` configuration defaults can be over-ridden by envars with the prefix "AIA_" followed by the config item name also in uppercase.
+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.
 
 | Config Item   | Default Value | envar key |
 | ------------- | ------------- | --------- |
@@ -231,9 +251,49 @@ The `aia` configuration defaults can be over-ridden by envars with the prefix "A
 
 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`
 
-## External CLI Tools Used
+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.
+
+## 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 "//"
+
+For example if a prompt text file has this line:
+
+> //config chat? = true
 
-From the verbose help text ...
+That prompt will enter the chat loop regardles of the presents of a "--chat" CLI option or the setting of the envar AIA_CHAT.
+
+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.
+
+See the [AIA::Directives](lib/aia/directives.rb) class to see what directives are available on the fromend within `aia`.
+
+See the [AIA::Mods](lib/aia/tools/mods.rb) class to for directives that are available to the `mods` backend.
+
+See the [AIA::Sgpt](lib/aia/tools/sgpt.rb) class to for directives that are available to the `sgpt` backend.
+
+## 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.
+
+For example consider:
+
+> 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.
+
+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
+
+Since `aia` supports parameterized prompts you could make a keyword like "[ROLE]" be part of your prompt.  For example consider this prompt:
+
+```text
+As a [ROLE] tell me what you think about [SUBJECT]
+```
+
+When this prompt is processed, `aia` will ask you for a value for the keyword "ROLE" and the keyword "SUBJECT" to complete the prompt.  Since `aia` maintains a history your previous answers, you could just choose something that you used in the past or answer with a completely new value.
+
+## External CLI Tools Used
 
 ```text
 External Tools Used
@@ -271,6 +331,22 @@ 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
+
+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:
+
+> [WHAT NOW HUMAN]
+
+Yep.  Just a single parameter for which I can provide a value of anything that is on my mind at the time.  Its advantage is that I do not pollute my shell's command history with lots of text.
+
+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
+
+> 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
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -279,6 +355,21 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/aia.
 
+I've designed `aia` so that it should be easy to integrate other backend LLM processors.  If you've found one that you like, send me a pull request or a feature request.
+
+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.
+
+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.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/aia/cli.rb

@@ -117,7 +117,8 @@ class AIA::Cli
       #           Default
       # Key       Value,      switches
       arguments:  [args], # NOTE: after process, prompt_id and context_files will be left
-      extra:      [''],   # SMELL: should be nil?
+      directives: [[]],   # an empty Array as the default value
+      extra:      [''],   # 
       #
       model:      ["gpt-4-1106-preview",  "--llm --model"],
       #
@@ -130,14 +131,12 @@ class AIA::Cli
       version?:   [false,     "--version"],
       help?:      [false,     "-h --help"],
       fuzzy?:     [false,     "-f --fuzzy"],
-      search:     [nil,       "-s --search"],
       markdown?:  [true,      "-m --markdown --no-markdown --md --no-md"],
+      chat?:      [false,     "--chat"],
+      terse?:     [false,     "--terse"],
+      speak?:     [false,     "--speak"],
       #
-      # TODO: May have to process the
-      #       "~" character and replace it with HOME
-      #
-      # TODO: Consider using standard suffix of _dif and _file
-      #       to signal Pathname objects fo validation
+      role:       ['',        "-r --role"],
       #
       config_file:[nil,                       "-c --config"],
       prompts_dir:["~/.prompts",              "-p --prompts"],
@@ -194,13 +193,15 @@ class AIA::Cli
 
 
   def process_command_line_arguments
+    # get the options meant for the backend AI command
+    # doing this first in case there are any options that conflict
+    # between frontend and backend.
+    extract_extra_options
+
     @options.keys.each do |option|
       check_for option
     end
 
-    # get the options meant for the backend AI command
-    extract_extra_options
-
     bad_options = arguments.select{|a| a.start_with?('-')}
 
     unless bad_options.empty?

data/lib/aia/directives.rb

@@ -0,0 +1,66 @@
+# lib/aia/directives.rb
+
+require 'hashie'
+
+class AIA::Directives
+  def initialize( prompt: )
+    @prompt = prompt  # PromptManager::Prompt instance
+    AIA.config.directives = @prompt.directives
+  end
+
+
+  def execute_my_directives
+    return if AIA.config.directives.nil? || AIA.config.directives.empty?
+    
+    not_mine = []
+
+    AIA.config.directives.each do |entry|
+      directive   = entry[0].to_sym
+      parameters  = entry[1]
+
+      if respond_to? directive
+        send(directive, parameters)
+      else
+        not_mine << entry
+      end
+    end
+
+    AIA.config.directives = not_mine
+  end
+
+
+  def box(what)
+    f   = what[0]
+    bar = "#{f}"*what.size
+    puts "#{bar}\n#{what}\n#{bar}"
+  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(' ')
+    item  = parts.shift
+    parts.shift if %w[:= =].include? parts[0]
+
+    if '<<' == parts[0]
+      parts.shift
+      value = parts.join
+      if AIA.config(item).is_a?(Array)
+        AIA.config[item] << value
+      else
+        AIA.config[item] = [ value ]
+      end
+    else
+      value = parts.join
+      if item.end_with?('?')
+        AIA.config[item] = %w[1 y yea yes t true].include?(value.downcase)
+      else
+        AIA.config[item] = "STDOUT" == value ? STDOUT : value
+      end
+    end
+  end
+end