prompt_manager 0.4.1 → 0.5.0

data/lib/prompt_manager/storage/file_system_adapter.rb

@@ -3,36 +3,45 @@
 # Use the local (or remote) file system as a place to
 # store and access prompts.
 #
-# Adds two additional methods to the Promp class:
+# Adds two additional methods to the Prompt class:
 #   list - returns Array of prompt IDs
-#   path = returns a Pathname object to the prompt's text file
+#   path - returns a Pathname object to the prompt's text file
 #   path(prompt_id) - same as path on the prompt instance
 #
 # Allows sub-directories of the prompts_dir to be
-# used like categories.  For example the prompt_id "toy/magic"
+# used like categories. For example the prompt_id "toy/magic"
 # is found in the `magic.txt` file inside the `toy` sub-directory
 # of the prompts_dir.
 #
-# There can man be many layers of categories (sub-directories)
+# There can be many layers of categories (sub-directories)
 #
+# This adapter serves as the file-based storage backend for PromptManager::Prompt,
+# enabling prompt retrieval and persistence using file system operations.
 
 require 'json'      # basic serialization of parameters
 require 'pathname'
+require 'fileutils'
 
 class PromptManager::Storage::FileSystemAdapter
-  SEARCH_PROC       = nil # placeholder
+  # Placeholder for search proc
+  SEARCH_PROC       = nil
+  # File extension for parameters
   PARAMS_EXTENSION  = '.json'.freeze
+  # File extension for prompts
   PROMPT_EXTENSION  = '.txt'.freeze
+  # Regular expression for valid prompt IDs
   PROMPT_ID_FORMAT  = /^[a-zA-Z0-9\-\/_]+$/
 
   class << self
-    attr_accessor :prompts_dir, :search_proc, 
+    # Accessors for configuration options
+    attr_accessor :prompts_dir, :search_proc,
                   :params_extension, :prompt_extension
-  
+
+    # Configure the adapter
     def config
       if block_given?
         yield self
-        validate_configuration     
+        validate_configuration
       else
         raise ArgumentError, "No block given to config"
       end
@@ -48,7 +57,6 @@ class PromptManager::Storage::FileSystemAdapter
       new.list
     end
 
-
     def path(prompt_id)
       new.path(prompt_id)
     end
@@ -56,6 +64,7 @@ class PromptManager::Storage::FileSystemAdapter
     #################################################
     private
 
+    # Validate the configuration
     def validate_configuration
       validate_prompts_dir
       validate_search_proc
@@ -63,28 +72,33 @@ class PromptManager::Storage::FileSystemAdapter
       validate_params_extension
     end
 
-
+    # Validate the prompts directory
     def validate_prompts_dir
-      # This is a work around for a Ruby scope issue where the 
-      # class getter/setter method is becoming confused with a 
-      # local variable when anything other than plain 'ol get and 
-      # set are used.'This error is in both Ruby v3.2.2 and
+      # This is a work around for a Ruby scope issue where the
+      # class getter/setter method is becoming confused with a
+      # local variable when anything other than plain 'ol get and
+      # set are used. This error is in both Ruby v3.2.2 and
       # v3.3.0-preview3.
       #
       prompts_dir_local = self.prompts_dir
 
+      raise ArgumentError, "prompts_dir must be set" if prompts_dir_local.nil? || prompts_dir_local.to_s.strip.empty?
+
       unless prompts_dir_local.is_a?(Pathname)
-        prompts_dir_local = Pathname.new(prompts_dir_local) unless prompts_dir_local.nil?
+        prompts_dir_local = Pathname.new(prompts_dir_local)
       end
 
       prompts_dir_local = prompts_dir_local.expand_path
 
-      raise(ArgumentError, "prompts_dir: #{prompts_dir_local}") unless prompts_dir_local.exist? && prompts_dir_local.directory?
-      
+      unless prompts_dir_local.exist?
+        FileUtils.mkdir_p(prompts_dir_local)
+      end
+      raise(ArgumentError, "prompts_dir: #{prompts_dir_local} is not a directory") unless prompts_dir_local.directory?
+
       self.prompts_dir = prompts_dir_local
     end
 
-
+    # Validate the search proc
     def validate_search_proc
       search_proc_local = self.search_proc
 
@@ -97,7 +111,7 @@ class PromptManager::Storage::FileSystemAdapter
       self.search_proc = search_proc_local
     end
 
-
+    # Validate the prompt extension
     def validate_prompt_extension
       prompt_extension_local = self.prompt_extension
 
@@ -113,7 +127,7 @@ class PromptManager::Storage::FileSystemAdapter
       self.prompt_extension = prompt_extension_local
     end
 
-
+    # Validate the params extension
     def validate_params_extension
       params_extension_local = self.params_extension
 
@@ -130,25 +144,25 @@ class PromptManager::Storage::FileSystemAdapter
     end
   end
 
-
   ##################################################
   ###
   ##  Instance
   #
 
+  # Accessors for instance variables
   def prompts_dir       = self.class.prompts_dir
   def search_proc       = self.class.search_proc
   def prompt_extension  = self.class.prompt_extension
   def params_extension  = self.class.params_extension
 
-
+  # Initialize the adapter
   def initialize
     # NOTE: validate because main program may have made
     #       changes outside of the config block
     self.class.send(:validate_configuration) # send gets around private designations of a method
   end
 
-
+  # Get a prompt by ID
   def get(id:)
     validate_id(id)
     verify_id(id)
@@ -160,17 +174,15 @@ class PromptManager::Storage::FileSystemAdapter
     }
   end
 
-
   # Retrieve prompt text by its id
   def prompt_text(prompt_id)
     read_file(file_path(prompt_id, prompt_extension))
   end
 
-
   # Retrieve parameter values by its id
   def parameter_values(prompt_id)
     params_path = file_path(prompt_id, params_extension)
-    
+
     if params_path.exist?
       parms_content = read_file(params_path)
       deserialize(parms_content)
@@ -179,35 +191,33 @@ class PromptManager::Storage::FileSystemAdapter
     end
   end
 
-
   # Save prompt text and parameter values to corresponding files
   def save(
-      id:, 
-      text: "", 
+      id:,
+      text: "",
       parameters: {}
     )
     validate_id(id)
 
     prompt_filepath = file_path(id, prompt_extension)
     params_filepath = file_path(id, params_extension)
-    
+
     write_with_error_handling(prompt_filepath, text)
     write_with_error_handling(params_filepath, serialize(parameters))
   end
 
-
-  # Delete prompted text and parameter values files
+  # Delete prompt text and parameter values files
   def delete(id:)
     validate_id(id)
 
     prompt_filepath = file_path(id, prompt_extension)
     params_filepath = file_path(id, params_extension)
-    
+
     delete_with_error_handling(prompt_filepath)
     delete_with_error_handling(params_filepath)
   end
 
-
+  # Search for prompts
   def search(for_what)
     search_term = for_what.downcase
 
@@ -218,25 +228,23 @@ class PromptManager::Storage::FileSystemAdapter
     end
   end
 
-
   # Return an Array of prompt IDs
   def list(*)
     prompt_ids = []
-    
+
     Pathname.glob(prompts_dir.join("**/*#{prompt_extension}")).each do |file_path|
       prompt_id = file_path.relative_path_from(prompts_dir).to_s.gsub(prompt_extension, '')
       prompt_ids << prompt_id
     end
 
-    prompt_ids
+    prompt_ids.sort
   end
 
-
   # Returns a Pathname object for a prompt ID text file
   # However, it is possible that the file does not exist.
   def path(id)
     validate_id(id)
-    file_path(id, prompt_extension) 
+    file_path(id, prompt_extension)
   end
 
   ##########################################
@@ -247,14 +255,14 @@ class PromptManager::Storage::FileSystemAdapter
     raise ArgumentError, "Invalid ID format id: #{id}" unless id =~ PROMPT_ID_FORMAT
   end
 
-
+  # Verify that the ID exists
   def verify_id(id)
     unless file_path(id, prompt_extension).exist?
       raise ArgumentError, "Invalid prompt_id: #{id}"
     end
   end
 
-
+  # Write to a file with error handling
   def write_with_error_handling(file_path, content)
     begin
       file_path.write content
@@ -264,8 +272,7 @@ class PromptManager::Storage::FileSystemAdapter
     end
   end
 
-
-  # file_path (Pathname)
+  # Delete a file with error handling
   def delete_with_error_handling(file_path)
     begin
       file_path.delete
@@ -275,39 +282,37 @@ class PromptManager::Storage::FileSystemAdapter
     end
   end
 
-
+  # Get the file path for a prompt ID and extension
   def file_path(id, extension)
     prompts_dir + "#{id}#{extension}"
   end
 
-
+  # Read a file
   def read_file(full_path)
     raise IOError, 'File does not exist' unless File.exist?(full_path)
     File.read(full_path)
   end
 
-
+  # Search for prompts
   def search_prompts(search_term)
     prompt_ids = []
-    
+
     Pathname.glob(prompts_dir.join("**/*#{prompt_extension}")).each do |prompt_path|
       if prompt_path.read.downcase.include?(search_term)
-        prompt_id = prompt_path.relative_path_from(prompts_dir).to_s.gsub(prompt_extension, '')    
+        prompt_id = prompt_path.relative_path_from(prompts_dir).to_s.gsub(prompt_extension, '')
         prompt_ids << prompt_id
       end
     end
 
-    prompt_ids
+    prompt_ids.sort
   end
 
-
-  # TODO: Should the serializer be generic?
-
+  # Serialize data to JSON
   def serialize(data)
     data.to_json
   end
 
-
+  # Deserialize JSON data
   def deserialize(data)
     JSON.parse(data)
   end

data/lib/prompt_manager/storage.rb

@@ -1,7 +1,34 @@
 # prompt_manager/lib/prompt_manager/storage.rb
 
+# The Storage module provides a namespace for different storage adapters
+# that handle persistence of prompts. Each adapter implements a common
+# interface for saving, retrieving, searching, and deleting prompts.
+#
+# Available adapters:
+# - FileSystemAdapter: Stores prompts in text files on the local filesystem
+# - ActiveRecordAdapter: Stores prompts in a database using ActiveRecord
+#
+# To use an adapter, configure it before using PromptManager::
+#
+# Example with FileSystemAdapter:
+#   PromptManager::Storage::FileSystemAdapter.config do |config|
+#     config.prompts_dir = Pathname.new('/path/to/prompts')
+#   end
+#   PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new
+#
+# Example with ActiveRecordAdapter:
+#   PromptManager::Storage::ActiveRecordAdapter.config do |config|
+#     config.model = MyPromptModel
+#     config.id_column = :prompt_id
+#     config.text_column = :content
+#     config.parameters_column = :params
+#   end
+#   PromptManager::Prompt.storage_adapter = PromptManager::Storage::ActiveRecordAdapter.new
 module PromptManager
+  # The Storage module provides adapters for different storage backends.
+  # Each adapter implements a common interface for managing prompts.
+  # Note: PromptManager::Prompt uses one of these adapters as its storage backend to
+  # perform all CRUD operations on prompt data.
   module Storage
   end
 end
-

data/lib/prompt_manager/version.rb

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

data/lib/prompt_manager.rb

@@ -2,11 +2,23 @@
 #
 # frozen_string_literal: true
 
+require 'ostruct'
+
 require_relative "prompt_manager/version"
-require_relative "prompt_manager/storage"
 require_relative "prompt_manager/prompt"
+require_relative "prompt_manager/storage"
+require_relative "prompt_manager/storage/file_system_adapter"
 
+# The PromptManager module provides functionality for managing, storing,
+# retrieving, and parameterizing text prompts used with generative AI systems.
+# It supports different storage backends through adapters and offers features
+# like parameter substitution, directives processing, and comment handling.
 module PromptManager
+  # Base error class for all PromptManager-specific errors
   class Error < StandardError; end
-  # TODO: Add some more module specific errors here
+
+  # 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
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: prompt_manager
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-29 00:00:00.000000000 Z
+date: 2025-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -66,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tocer
   requirement: !ruby/object:Gem::Requirement
@@ -80,8 +93,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: "Manage the parameterized prompts (text) used in generative AI (aka chatGPT,
-  \nOpenAI, et.al.) using storage adapters such as FileSystemAdapter, \nSqliteAdapter
+  \nOpenAI, et.al.) using storage adapters such as FileSystemAdapter, \nSqliteAdapter,
   and ActiveRecordAdapter.\n"
 email:
 - dvanhoozer@gmail.com
@@ -90,11 +131,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
+- ".irbrc"
 - CHANGELOG.md
 - LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/directives.rb
 - examples/prompts_dir/todo.json
 - examples/prompts_dir/todo.txt
 - examples/prompts_dir/toy/8-ball.txt
@@ -102,6 +145,7 @@ files:
 - examples/simple.rb
 - examples/using_search_proc.rb
 - lib/prompt_manager.rb
+- lib/prompt_manager/directive_processor.rb
 - lib/prompt_manager/prompt.rb
 - lib/prompt_manager/storage.rb
 - lib/prompt_manager/storage/active_record_adapter.rb
@@ -115,7 +159,6 @@ metadata:
   homepage_uri: https://github.com/MadBomber/prompt_manager
   source_code_uri: https://github.com/MadBomber/prompt_manager
   changelog_uri: https://github.com/MadBomber/prompt_manager
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -130,8 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.6
 specification_version: 4
 summary: Manage prompts for use with gen-AI processes
 test_files: []