aia 0.3.4 → 0.3.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bfe9daa39adc44a512d9c78f59e7f784f526c8983563dc87441cf25bb34a5a7
-  data.tar.gz: 15d0dc829ebda2761d0b396b9c3069aba2b1c9224f4e091c024fc5cfadd2f93b
+  metadata.gz: 505546a036010eb8b0360f7fbfbb4c6494c311e98969c8095fa091882815aac2
+  data.tar.gz: 6f9323e50879c3b51a5ead99c29b1b41fc377dc1957283edb13e03bb30c866db
 SHA512:
-  metadata.gz: b9da70fa3aa58b3430732df71cc1e39990d9236d18e754582e5c83341a2b094115628e30d8c0f2ef70e1df371e6de0733b6bbe10bac09e1281f37d7447036b3f
-  data.tar.gz: 143637cb1e2fedbe8456327220181b9cbba152ed948b3b9eb4bb382b219137eea2c4d78ec530ac3b76d981f9e8c06dd83ec7f595772d5c07fc95f8a245805241
+  metadata.gz: 23926f77a010a023fd1fbbde152f83cfacd75f003bb2e060d4e2b4ca0cd7aecac6631b0520c5e3c6d56cbde31914f158f520f15bfa239a1a72bf682c5ea79032
+  data.tar.gz: 9d76ab35f70a13a4320d9fb4ee5f3fd47e4039c95e99fc02ce858977e179d1891d44fb08cf7cfc17975e6828dbe28d01d9d778d949c371e898e847e7fa865020

data/.semver

@@ -0,0 +1,6 @@
+---
+:major: 0
+:minor: 3
+:patch: 19
+:special: ''
+:metadata: ''

data/CHANGELOG.md

@@ -1,4 +1,16 @@
 ## [Unreleased]
+## [0.3.19] 2023-12-26
+- major code refactoring.
+- supports config files \*.yml, \*.yaml and \*.toml
+- usage implemented as a man page. --help will display the man page/
+- added "--dump <yml|yaml|toml>" to send current configuration to STDOUT
+- added "--completion <bash|fish|zsh>" to send a a completion function for the indicated shell to STDOUT
+- added system environment variable (envar) over-rides of default config values uppercase environment variables prefixed with "AIA_" + config item name for example AIA_PROMPTS_DIR and AIA_MODEL.  All config items can be over-ridden by their cooresponding envars.
+- config value hierarchy is:
+    1. values from config file  over-rides ...
+    2. command line values      over-rides ...
+    3. envar values             over-rides ...
+    4. default values
 
 ## [0.3.0] = 2023-11-23
 

data/README.md

@@ -6,8 +6,7 @@ Uses the gem "prompt_manager" to manage the prompts sent to the `mods` command-l
 
 **Most Recent Change**
 
-v0.3.0 - Matching version to [prompt_manager](https://github.com/prompt_manager) This version allows for the user of history in the entery of values to prompt keywords.  KW_HISTORY_MAX is set at 5.  Changed CLI enteraction to use historical selection and editing of prior keyword values.
-
+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.
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -15,8 +14,9 @@ v0.3.0 - Matching version to [prompt_manager](https://github.com/prompt_manager)
 
   - [Installation](#installation)
   - [Usage](#usage)
-  - [System Environment Variables (envars)](#system-environment-variables-envars)
+  - [System Environment Variables (envar)](#system-environment-variables-envar)
   - [External CLI Tools Used](#external-cli-tools-used)
+  - [Shell Completion](#shell-completion)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
@@ -47,83 +47,190 @@ TODO: don't forget to mention have access token (API keys) setup as envars for t
 
 ## Usage
 
+The usage report obtained using either `-h` or `--help` is implemented as a standard `man` page.  You can use both `--help --verbose` of `-h -v` together to get not only the `aia` man page but also the usage report from the `backend` LLM processing tool.
+
 ```text
 $ aia --help
 
-aia v0.0.5
+aia(1)                           User Manuals                           aia(1)
 
-Usage:  aia [options] prompt_id [context_file]* [-- external_options+]
+NAME
+       aia - command-line interface for an AI assistant
 
-Options
--------
+SYNOPSIS
+       aia [options]* PROMPT_ID [CONTEXT_FILE]* [-- EXTERNAL_OPTIONS+]
 
-Edit the Prompt File  -e --edit
- default: false
+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.
 
-Turn On Debugging     -d --debug
- default: false
+ARGUMENTS
+       PROMPT_ID
+              This is a required argument.
 
-Be Verbose            -v --verbose
- default: false
+       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.
 
-Print Version         --version
- default: false
+       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.
 
-Show Usage            -h --help
- default: false
+OPTIONS
+       -c, --config PATH_TO_CONFIG_FILE
+              Load Config File - default: nil
 
-Use Fuzzy Matching    --fuzzy
- default: false
+       --dump FORMAT
 
-Out FILENAME          -o --output --no-output
- default: ./temp.md
+       -e, --edit
+              Edit the Prompt File - default: false
 
-Log FILEPATH          -l --log --no-log
- default: $HOME/.prompts/_prompts.log
+       -d, --debug
+              Turn On Debugging - default: false
 
-Format with Markdown  -m --markdown --no-markdown --md --no-md
- default: true
-```
+       -v, --verbose
+              Be Verbose - default: false
 
-Turn on `verbose` with `help` to see more usage information that includes system environment variables and external CLI tools that are used.
+       --version
+              Print Version - default: false
 
-```text
-$ aia --help --verbose
-```
+       -h, --help
+              Show Usage - default: false
 
-## System Environment Variables (envars)
+       -s, --search TERM
+              Search for prompts contain TERM - default: nil
 
-From the verbose help text ...
+       -f, --fuzzy`
+              Use Fuzzy Matching when searching for a prompt - default: false
 
-```text
+       --completion SHELL_NAME
+
+       -o, --[no]-output PATH_TO_OUTPUT_FILE
+              Out FILENAME - default: ./temp.md
+
+       -l, --[no]-log PATH_TO_LOG_FILE
+              Log FILEPATH - default: $HOME/.prompts/prompts.log
+
+       -m, --[no]-markdown
+              Format with Markdown - default: true
+
+       --model NAME
+              Name of the LLM model to use - default: gpt-4-1106-preview
+
+       -p, --prompts PATH_TO_DIRECTORY
+              Directory containing the prompt files - default: ~/.prompts
+
+       -b, --[no]-backend LLM TOOL
+              Specify the backend prompt resolver - default: :mods
+
+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
+
+              • EDITOR: The text editor used by the edit option - default:
+                edit
 
-System Environment Variables Used
----------------------------------
+              • AIA_MODEL: The AI model specification - default:
+                gpt-4-1106-preview
 
-The OUTPUT and PROMPT_LOG envars can be overridden
-by cooresponding options on the command line.
+              • AIA_OUTPUT: The default filename for output - default:
+                ./temp.md
 
-Name            Default Value
---------------  -------------------------
-PROMPTS_DIR     $HOME/.prompts_dir
-AI_CLI_PROGRAM  mods
-EDITOR          edit
-MODS_MODEL      gpt-4-1106-preview
-OUTPUT          ./temp.md
-PROMPT_LOG      $PROMPTS_DIR/_prompts.log
+              • AIA_PROMPT_LOG: The default filepath for the prompts log -
+                default: $HOME/.prompts/_prompts.log
 
-These two are required for access the OpenAI
-services.  The have the same value but different
-programs use different envar names.
+       Additionally, the program requires an OpenAI access key, which can be
+       specified using one of the following environment variables:
 
-To get an OpenAI access key/token (same thing)
-you must first create an account at OpenAI.
-Here is the link:  https://platform.openai.com/docs/overview
+              • 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.
+
+       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.
+
+       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.
+
+SEE ALSO
+
+              • 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
+                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.
+
+AUTHOR
+       Dewayne VanHoozer <dvanhoozer@gmail.com>
+
+AIA                               2024-01-01                            aia(1)
 
-OPENAI_ACCESS_TOKEN
-OPENAI_API_KEY
 ```
 
+## 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.
+
+| Config Item   | Default Value | envar key |
+| ------------- | ------------- | --------- |
+| backend       | mods          | AIA_BACKEND |
+| config_file   | nil           | AIA_CONFIG_FILE |
+| debug         | false         | AIA_DEBUG |
+| edit          | false         | AIA_EDIT |
+| extra         | ''            | AIA_EXTRA |
+| fuzzy         | false         | AIA_FUZZY |
+| 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 |
+| 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`
+
 ## External CLI Tools Used
 
 From the verbose help text ...
@@ -156,10 +263,13 @@ export EDITOR="subl -w"
 
 ## Shell Completion
 
-One of the executables with this gem is `aia_completion.sh` which contains a completion script for hte `aia` such that you specify the first few characters of a prompt ID on the command line and the shell will complete the rest of the ID for you.  It works with the `bash` shell but do not know whether it works with the other shells.
+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`
 
-To set the completion you can execute aia_completion.sh` in your `.bashrc`  however, the PROMPTS_DIR environment variable must be set in order for prompt ID to work correctly.
+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.
 
 ## Development
 

data/Rakefile

@@ -8,6 +8,8 @@ end
 
 Tocer::Rake::Register.call
 
+require 'kramdown/man/task'
+Kramdown::Man::Task.new
 
 require "bundler/gem_tasks"
 require "rake/testtask"

data/justfile

@@ -0,0 +1,167 @@
+# aia/main.just
+#
+# Support man pages with ...
+# gem install kramdown-man
+#
+
+RR := env_var('RR')
+
+# with ~/.justfile
+
+# >>> /Users/dewayne/.justfile
+# ~/.justfile
+# brew install just
+# gem install justprep OR brew install justprep for the Crystal version
+# alias jj='justprep && just'
+#
+# See: https://cheatography.com/linux-china/cheat-sheets/justfile/
+#
+
+# high-level just directives
+
+set fallback # search up for recipe name if not found locally.
+
+set positional-arguments    := true
+set allow-duplicate-recipes := true
+set dotenv-load             := false
+
+# my common variables
+
+pwd         := env_var('PWD')
+
+me          := justfile()
+home        := env_var('HOME')
+backup_dir  := env_var('JUST_BACKUP_DIR')
+backup_file := trim_start_match(me, home)
+my_backup   := backup_dir + backup_file
+project     := "`basename $RR`"
+
+
+# List available recipes
+@list:
+  echo
+  echo "Available Recipes at"
+  echo "$PWD"
+  echo "are:"
+  echo
+  just -l --list-prefix 'jj ' --list-heading ''
+  echo
+  echo "jj <module_name> to see sub-tasks"
+  echo
+
+
+# Show help/usage for "just" command
+@help: list
+  just --help
+
+
+# Backup .envrc & *.just files
+@backup_support_files: _backup_all_just_files _backup_all_envrc_files
+
+
+# Backup all changed just files to $JUST_BACKUP_DIR
+@_backup_all_just_files:
+  backup_just.rb
+
+
+# backup all changed envrc files to ENVRC_BACKUP_DIR
+@_backup_all_envrc_files:
+  backup_envrc.rb
+
+
+#################################################
+## Private recipes
+
+# Show private recipes
+@show_private:     # Show private recipes
+  grep -B 1 "^[@]_" {{justfile()}}
+
+
+# Show the differences between this justfile and is last backup
+@_just_diff_my_backup:
+  # echo "me          -=> {{me}}"
+  # echo "home        -=> {{home}}"
+  # echo "backup_file -=> {{backup_file}}"
+  # echo "my_backup   -=> {{my_backup}}"
+
+  @diff {{me}} {{my_backup}}
+
+
+# Replace current justfile with most recent backup
+@_just_restore_me_from_backup:
+  echo
+  echo "Do this because I will not ..."
+  echo
+  echo "cp -f {{my_backup}} {{me}}"
+  echo
+
+
+# Edit the $JUSTPREP_FILENAME_IN file
+@_just_edit_me:
+  $EDITOR {{me}}
+# <<< /Users/dewayne/.justfile
+
+# FIXME: justprep module process still has an issue with ~ and $HOME
+# FIXME: justprep does not like more than one space between module name and path.
+
+module_repo := "/Users/dewayne/sandbox/git_repos/repo.just"
+module_gem := "/Users/dewayne/sandbox/git_repos/gem.just"
+module_version := "/Users/dewayne/just_modules/version.just"
+
+
+# Preview man page
+preview_man_page:
+  kramdown-man {{RR}}/man/aia.1.md
+
+
+# View man page
+view_man_page: create_man_page
+  man {{RR}}/man/aia.1
+
+
+# Create man page
+create_man_page:
+  rake man
+
+##########################################
+
+# Tag the current commit, push it, then bump the version
+tag_push_and_bump: tag push bump
+
+
+# Create a git tag for the current version
+tag:
+  git tag $(semver)
+
+# Push the git current working directory and all tags
+push:
+  git push
+  git push origin --tags
+
+
+alias inc := bump
+
+# Increament version's level: major.minor.patch
+@bump level='patch':
+  semver increment {{level}}
+  echo "Now working on: $(semver)"
+  git add {{RR}}/.semver
+
+
+
+# Module repo
+@repo what='' args='':
+  just -d . -f {{module_repo}} {{what}} {{args}}
+
+
+
+# Module gem
+@gem what='' args='':
+  just -d . -f {{module_gem}} {{what}} {{args}}
+
+
+
+# Module version
+@version what='' args='':
+  just -d . -f {{module_version}} {{what}} {{args}}
+