prompt_manager 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9520d380488f2d4ef62d07dfc4a9b27bcc66086f5adb1f2d6fa874e8e179cfd3
-  data.tar.gz: 1df0ea5efe721cd24293ed2172a72406b0e649e61a6778bb25615121c0ab39cb
+  metadata.gz: 0006a09365e6585250c1b22f102502d22bad785f8b6de23ac440a5669779a79e
+  data.tar.gz: 646b4bc31e96bff683a3ef9f177f60a8b81bc7c892de9d0c32a13cb2fd1ebfda
 SHA512:
-  metadata.gz: ed5b5fdb6592797bd3bb5a564f13235360e8fde690e0781d51b39deb5f2d26590173bc2257f78dae132d2d91b12c27bf246d392c7cb9a84b1f22c1b409b88004
-  data.tar.gz: 76425c4b30f68977dd4e16513c53bac2bc84e277e7e209dc1eb57f5f9f2267d23b354fd8d2fe79f871c05c0672198b53db4fe687b38966350c1aa0540e158913
+  metadata.gz: 94756fc51e3f52c8cdcbc0695569b0d8c3c2ac5f2ae1adbcf9c9a8c4854c80a2ae40cde4e09fe2186dd478d758bf1f7d847353824bfc9648013b8142c28c67a8
+  data.tar.gz: e00d4f971f0a5830dfc4cae7ff439965e02be05756e0ccaf3c37fe93df8e0709abc19061debef78f7e4c9746294a1b58ed26a7c22b121c8f1061ab727dbbf4c6

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 ## Unreleased
 
 ## Released
+
+### [0.5.3] = 2025-05-14
+- fixed issue were directives were not getting their content added to the prompt text
+- Updated documentation and versioning.
+- Added new error classes for better error handling.
+- Improved parameter handling and directive processing.
+
 ### [0.5.0] = 2025-03-29
 - Major refactoring of to improve processing of parameters and directives.
 - Added PromptManager::DirectiveProcessor as an example of how to implement custom directives.

data/README.md

@@ -1,32 +1,33 @@
 # PromptManager
 
-Manage the parameterized prompts (text) used in generative AI (aka chatGPT, OpenAI, _et.al._) using storage adapters such as FileSystemAdapter, SqliteAdapter and ActiveRecordAdapter.
-
-**Breaking Change** in version 0.3.0 - The value of the parameters Hash for a keyword is now an Array instead of a single value.  The last value in the Array is always the most recent value used for the given keyword.  This was done to support the use of a Readline::History object editing in the [aia](https://github.com/MadBomber/aia) CLI tool
+Manage the parameterized prompts (text) used in generative AI (aka chatGPT, OpenAI, _et.al._) using storage adapters such as FileSystemAdapter and ActiveRecordAdapter.
 
+**Current Version**: 0.5.3
 
+**Breaking Change** in version 0.3.0 - The value of the parameters Hash for a keyword is now an Array instead of a single value.  The last value in the Array is always the most recent value used for the given keyword.  This was done to support the use of a Readline::History object editing in the [aia](https://github.com/MadBomber/aia) CLI tool
+### Latest Capabilities
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
-- [PromptManager](#promptmanager)
-  - [Table of Contents](#table-of-contents)
+    - [Latest Capabilities](#latest-capabilities)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Overview](#overview)
+    - [Prompt Initialization Options](#prompt-initialization-options)
     - [Generative AI (gen-AI)](#generative-ai-gen-ai)
       - [What does a keyword look like?](#what-does-a-keyword-look-like)
       - [All about directives](#all-about-directives)
         - [Example Prompt with Directives](#example-prompt-with-directives)
-        - [Accessing Directives and Setting Parameter Values](#accessing-directives-and-setting-parameter-values)
+        - [Accessing and Setting Parameter Values](#accessing-and-setting-parameter-values)
         - [Dynamic Directives](#dynamic-directives)
         - [Executing Directives](#executing-directives)
       - [Comments Are Ignored](#comments-are-ignored)
   - [Storage Adapters](#storage-adapters)
     - [FileSystemAdapter](#filesystemadapter)
       - [Configuration](#configuration)
-        - [prompts\_dir](#prompts_dir)
-        - [search\_proc](#search_proc)
+        - [prompts_dir](#prompts_dir)
+        - [search_proc](#search_proc)
         - [File Extensions](#file-extensions)
       - [Example Prompt Text File](#example-prompt-text-file)
       - [Example Prompt Parameters JSON File](#example-prompt-parameters-json-file)
@@ -34,21 +35,24 @@ Manage the parameterized prompts (text) used in generative AI (aka chatGPT, Open
     - [ActiveRecordAdapter](#activerecordadapter)
       - [Configuration](#configuration-1)
         - [model](#model)
-        - [id\_column](#id_column)
-        - [text\_column](#text_column)
-        - [parameters\_column](#parameters_column)
+        - [id_column](#id_column)
+        - [text_column](#text_column)
+        - [parameters_column](#parameters_column)
     - [Other Potential Storage Adapters](#other-potential-storage-adapters)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
-### Latest Capabilities
+
+
 - **Directive Processing:** Processes directives such as `//include` (aliased as `//import`) with loop protection.
 - **ERB Processing:** Supports ERB templating within prompts.
 - **Environment Variable Embedding:** Automatically substitutes system environment variables in prompts.
-- **Improved Parameter Handling:** Refactored to maintain a history of parameter values.
+- **Improved Parameter Handling:** Refactored to maintain a history of parameter values and added error handling for parameter substitution.
 - **ActiveRecord Adapter:** Facilitates storing and retrieving prompts via an ActiveRecord model.
+- **Enhanced Error Handling:** Added specific error classes for better error handling, including StorageError, ParameterError, and ConfigurationError.
+- **Customizable Keyword Pattern:** Ability to customize the pattern used for detecting keywords in prompts.
 
 ## Installation
 
@@ -100,13 +104,13 @@ The regex must include capturing parentheses () to extract the keyword. The defa
 
 A directive is a line in the prompt text that starts with the two characters '//' - slash slash - just like in the old days of IBM JCL - Job Control Language.  A prompt can have zero or more directives.  Directives can have parameters and can make use of keywords.
 
-The `prompt_manager` only collects directives.  It extracts keywords from directive lines and provides the substitution of those keywords with other text just like it does for the prompt.
+The `prompt_manager` collects directives and provides a DirectiveProcessor class that currently implements the `//include` directive (also aliased as `//import`), which allows including content from other files with loop protection. It extracts keywords from directive lines and provides the substitution of those keywords with other text just like it does for the prompt.
 
 ##### Example Prompt with Directives
 
 Here is an example prompt text file with comments, directives and keywords:
 
-```
+```text
 # prompts/sing_a_song.txt
 # Desc: Has the computer sing a song
 
@@ -118,42 +122,36 @@ __END__
 Computers will never replace Frank Sinatra
 ```
 
-##### Accessing Directives and Setting Parameter Values
+##### Accessing and Setting Parameter Values
 
-Getting directives and keywords from a prompt is straightforward:
+Getting and setting keywords from a prompt is straightforward:
 
 ```ruby
 prompt = PromptManager::Prompt.new(id: 'some_id')
 prompt.keywords   #=> an Array of keywords found in the prompt text
-prompt.directives #=> an Array of entries like: ['directive', 'parameters']
 
-# Or directly update the parameters hash
+# Update the parameters hash with keyword values
 prompt.parameters = {
   "[KEYWORD1]" => "value1",
   "[KEYWORD2]" => "value2"
 }
 
-# After setting parameter values, call to_s to build the final prompt
-# to_s builds the prompt by substituting
-# values for keywords and removing comments.
-# The resulting text contains directives and
-# prompt text ready for the LLM process.
+# Build the final prompt text
+# This substitutes values for keywords and processes directives
+# Comments are removed and the result is ready for the LLM
 final_text = prompt.to_s
 
-# To persist any parameter changes to storage
+# Save any parameter changes back to storage
 prompt.save
 ```
 
-The entries in the Array returned by the `prompt.directives` method is in the order that the directives were defined within the prompt.  Each entry has two elements:
-
-- directive name (without the // characters)
-- parameter string for the directive
+Internally, directives are stored in a Hash where each key is the full directive line (including the // characters) and the value is the result string from executing that directive. The directives are processed in the order they appear in the prompt text.
 
 ##### Dynamic Directives
 
 Since directies are collected after the keywords in the prompt have been substituted for their values, it is possible to have dynamically generated directives as part of a prompt.  For example:
 
-```
+```text
 //[COMMAND] [OPTIONS]
 # or
 [SOMETHING]
@@ -162,11 +160,12 @@ Since directies are collected after the keywords in the prompt have been substit
 
 ##### Executing Directives
 
-The `prompt_manager` gem only collects directives.  Executing those directives is left up to some down stream process.  Here are some ideas on how directives could be used in prompt downstream process:
+The `prompt_manager` gem provides a basic DirectiveProcessor class that handles the `//include` directive (aliased as `//import`), which adds the contents of a file to the prompt with loop protection to prevent circular includes.
+
+Additionally, you can extend with your own directives or downstream processes. Here are some ideas on how directives could be used in prompt downstream process:
 
 - "//model gpt-5" could be used to set the LLM model to be used for a specific prompt.
 - "//backend mods" could be used to set the backend prompt processor on the command line to be the `mods` utility.
-- "//include path_to_file" could be used to add the contents of a file to the prompt.
 - "//chat" could be used to send the prompts and then start up a chat session about the prompt and its response.
 
 Its all up to how your application wants to support directives or not.
@@ -180,7 +179,7 @@ The gem also ignores blank lines.
 
 ## Storage Adapters
 
-A storage adapter is a class instance that ties the `PromptManager::Prompt` class to a storage facility that holds the actual prompts. Currently there are 3 storage adapters planned for implementation.
+A storage adapter is a class instance that ties the `PromptManager::Prompt` class to a storage facility that holds the actual prompts. Currently there are 2 storage adapters implemented: FileSystemAdapter and ActiveRecordAdapter.
 
 The `PromptManager::Prompt` to support a small set of methods.  A storage adapter can provide "extra" class or instance methods that can be used through the Prompt class.  See the `test/prompt_manager/prompt_test.rb` for guidance on creating a new storage adapter.
 
@@ -274,8 +273,9 @@ The last value in the keyword's Array is the most recent value used for that key
 #### Extra Functionality
 
 The `FileSystemAdapter` adds two new methods for use by the `Prompt` class:
-* list - returns an Array of prompt IDs
-* path and path(prompt_id) - returns a `Pathname` object to the prompt file
+
+- list - returns an Array of prompt IDs
+- path and path(prompt_id) - returns a `Pathname` object to the prompt file
 
 Use the `path(prompt_id)` form against the `Prompt` class
 Use `prompt.path` when you have an instance of a `Prompt`
@@ -322,13 +322,13 @@ The `parameters_column` contains the name of the column that contains the parame
 
 TODO: fix the kludge so that any serialization can be used.
 
-
 ### Other Potential Storage Adapters
 
-There are many possibilities to example this plugin concept of the storage adapter.  Here are some for consideration:
+There are many possibilities to expand this plugin concept of the storage adapter.  Here are some for consideration:
 
-* RedisAdapter - Not sure; isn't redis more temporary oriented?
-* ApiAdapter - use some end-point to CRUD a prompt
+- RedisAdapter - For caching prompts or temporary storage
+- ApiAdapter - Use some end-point to CRUD a prompt
+- CloudStorageAdapter - Store prompts in cloud storage services
 
 ## Development
 
@@ -336,7 +336,7 @@ Looking for feedback and contributors to enhance the capability of prompt_manage
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/prompt_manager.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/MadBomber/prompt_manager](https://github.com/MadBomber/prompt_manager).
 
 ## License
 

data/examples/directives.rb

@@ -56,28 +56,25 @@ end
 PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new
 
 # Use {parameter name} brackets to define a parameter
-PromptManager::Prompt.parameter_regex =  /\{[A-Za-z _|]+\}/ 
+# Note: must include capturing parentheses to make scan return arrays
+PromptManager::Prompt.parameter_regex =  /(\{[A-Za-z _|]+\})/ 
 
 # Retrieve a prompt
-prompt = PromptManager::Prompt.get(id: 'directive_example')
+# Note: The 'get' method returns a Hash, not a Prompt object
+# Use 'find' instead to get a Prompt object with methods
+prompt = PromptManager::Prompt.find(id: 'directive_example')
 
 # Shows prompt without comments or directives
 # It still has its parameter placeholders
 puts prompt
 concept_break
 
-puts "Directives in the prompt:"
-ap prompt.directives
+puts "Directives are processed automatically when you call to_s on a prompt"
+puts "The DirectiveProcessor class handles directives like //include"
+puts "You don't need to process them manually"
 
-puts "Processing directives ..."
-prompt.directives.each do |entry|
-  if MyDirectives.respond_to? entry.first.to_sym
-    ruby = "MyDirectives.#{entry.first}(#{entry.last.gsub(' ', ',')})"
-    eval "#{ruby}"
-  else
-    puts "ERROR: there is no method: #{entry.first}"
-  end
-end
+puts "Custom directive processing can be done by creating a custom DirectiveProcessor"
+puts "and setting it when creating a Prompt instance:"
 
 concept_break
 
@@ -87,12 +84,19 @@ puts "Parameters in the prompt:"
 ap prompt.parameters
 puts "-"*16
 
-puts "keywords:"
-ap prompt.keywords
+# Extract parameters from the prompt text using the parameter_regex
+puts "Parameters identified in the prompt text:"
+# With a capturing group, scan returns an array of arrays, so we need to flatten
+prompt_params = prompt.text.scan(PromptManager::Prompt.parameter_regex).flatten
+ap prompt_params
 concept_break
 
-prompt.parameters['{language}'] << 'French'
+# Set a parameter value (should be a string, not appending to an array)
+prompt.parameters['{language}'] = 'French'
 
 puts "After Substitution"
 puts prompt
 
+# Save the updated parameters
+prompt.save
+

data/examples/prompts_dir/todo.json

@@ -1 +1 @@
-{"[LANGUAGE]":"ruby"}
+{"[LANGUAGE]":"ruby","[KEYWORD_AKA_TODO]":"TODO"}

data/examples/simple.rb

@@ -40,8 +40,10 @@ end
 PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new
 
 # Get a prompt
+# Note: The 'get' method returns a Hash, not a Prompt object
+# Use 'find' instead to get a Prompt object with methods
 
-todo = PromptManager::Prompt.get(id: 'todo')
+todo = PromptManager::Prompt.find(id: 'todo')
 
 # This sequence simulates presenting each of the previously
 # used values for each keyword to the user to accept or
@@ -55,10 +57,9 @@ todo = PromptManager::Prompt.get(id: 'todo')
 
 todo.parameters["[KEYWORD_AKA_TODO]"] = "TODO"
 
-# When the parameter values change, the prompt must 
-# must be rebuilt using the build method.
-
-todo.build 
+# When the parameter values change, the prompt must
+# be saved to persist the changes
+todo.save
 
 
 puts <<~EOS
@@ -98,7 +99,7 @@ puts <<~EOS
 
 EOS
 
-magic = PromptManager::Prompt.get( id: 'toy/8-ball' )
+magic = PromptManager::Prompt.find(id: 'toy/8-ball')
 
 puts "The magic PROMPT is:"
 puts magic
@@ -110,9 +111,9 @@ puts "="*64
 
 puts <<~EOS
 
-  The FileSystemAdapter also adds two new methods to the Prompt class:
+  The FileSystemAdapter also adds two new class methods to the Prompt class:
 
-    list - provides an Array of pompt IDs
+    list - provides an Array of prompt IDs
     path(prompt_id) - Returns a Pathname object to the prompt file
 
 EOS
@@ -126,7 +127,7 @@ puts <<~EOS
 
   And the path to the "toy/8-ball" prompt file is:
 
-  #{magic.path}
+  #{PromptManager::Prompt.path('toy/8-ball')}
 
   Use "your_prompt.path" for when you want to do something with the
   the prompt file like send it to a text editor.

data/lib/prompt_manager/prompt.rb

@@ -146,7 +146,7 @@ class PromptManager::Prompt
   def substitute_values(input_text, values_hash)
     if values_hash.is_a?(Hash) && !values_hash.empty?
       values_hash.each do |key, value|
-        input_text = input_text.gsub(key, value.last)
+        input_text = input_text.gsub(key, value)
       end
     end
     input_text

data/lib/prompt_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PromptManager
-  VERSION = "0.5.2"
+  VERSION = "0.5.3"
 end

data/lib/prompt_manager.rb

@@ -17,8 +17,12 @@ module PromptManager
   # Base error class for all PromptManager-specific errors
   class Error < StandardError; end
 
-  # TODO: Add additional module-specific error classes such as:
-  # - StorageError - For issues with storing or retrieving prompts
-  # - ParameterError - For issues with parameter substitution
-  # - ConfigurationError - For setup and configuration issues
+  # Error class for storage-related issues
+  class StorageError < Error; end
+
+  # Error class for parameter substitution issues
+  class ParameterError < Error; end
+
+  # Error class for configuration issues
+  class ConfigurationError < Error; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prompt_manager
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Dewayne VanHoozer