├── docs ├── .keep ├── core-features │ ├── directive-processing.md │ ├── comments.md │ ├── erb-integration.md │ ├── shell-integration.md │ ├── parameter-history.md │ └── error-handling.md ├── assets │ ├── logo.svg │ └── favicon.ico ├── getting-started │ ├── installation.md │ ├── quick-start.md │ └── basic-concepts.md ├── storage │ ├── custom-adapters.md │ ├── filesystem-adapter.md │ └── activerecord-adapter.md ├── index.md ├── api │ ├── prompt-class.md │ ├── configuration.md │ └── directive-processor.md ├── development │ └── roadmap.md └── examples.md ├── test ├── prompts_dir │ ├── test2_prompt.json │ ├── excluded.txt │ ├── included.txt │ ├── todo.json │ ├── new_prompt.json │ ├── new_prompt.txt │ ├── test2_prompt.txt │ ├── also_included.txt │ ├── test_prompt.json │ ├── test_prompt.txt │ ├── hello_prompt.txt │ ├── toy │ │ └── 8-ball.txt │ ├── test_parameters.txt │ ├── test_parameters_and_directives.txt │ ├── test_directives.txt │ └── todo.txt ├── prompt_manager │ ├── storage_test.rb │ ├── directive_processor_test.rb │ ├── storage │ │ ├── test_removed_keywords_bug.rb │ │ ├── active_record_adapter_test.rb │ │ └── file_system_adapter_test.rb │ └── prompt_test.rb ├── prompt_manager_test.rb ├── test_helper.rb └── test_prompt_features.rb ├── .envrc ├── examples ├── prompts_dir │ ├── directive_example.json │ ├── todo.json │ ├── toy │ │ └── 8-ball.txt │ ├── directive_example.txt │ ├── todo.txt │ └── advanced_demo.txt ├── advanced_integrations.rb ├── rgfzf ├── using_search_proc.rb ├── directives.rb └── simple.rb ├── prompt_manager_logo.png ├── lib ├── prompt_manager │ ├── version.rb │ ├── directive_processor.rb │ ├── storage.rb │ ├── storage │ │ ├── active_record_adapter.rb │ │ └── file_system_adapter.rb │ └── prompt.rb └── prompt_manager.rb ├── Gemfile ├── .gitignore ├── Rakefile ├── .irbrc ├── .github └── workflows │ └── docs.yml ├── LICENSE ├── prompt_manager.gemspec ├── CHANGELOG.md ├── Gemfile.lock ├── mkdocs.yml └── COMMITS.md /docs/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /test/prompts_dir/test2_prompt.json: -------------------------------------------------------------------------------- 1 | {} -------------------------------------------------------------------------------- /test/prompts_dir/excluded.txt: -------------------------------------------------------------------------------- 1 | this does not -------------------------------------------------------------------------------- /test/prompts_dir/included.txt: -------------------------------------------------------------------------------- 1 | this contains hello -------------------------------------------------------------------------------- /test/prompts_dir/todo.json: -------------------------------------------------------------------------------- 1 | {"[LANGUAGE]":"ruby"} -------------------------------------------------------------------------------- /test/prompts_dir/new_prompt.json: -------------------------------------------------------------------------------- 1 | {"name":"Rubyist"} -------------------------------------------------------------------------------- /test/prompts_dir/new_prompt.txt: -------------------------------------------------------------------------------- 1 | How are you, [NAME]? -------------------------------------------------------------------------------- /test/prompts_dir/test2_prompt.txt: -------------------------------------------------------------------------------- 1 | Hello, how are you? -------------------------------------------------------------------------------- /.envrc: -------------------------------------------------------------------------------- 1 | # prompt_manager/.envrc 2 | 3 | export RR=`pwd` 4 | -------------------------------------------------------------------------------- /examples/prompts_dir/directive_example.json: -------------------------------------------------------------------------------- 1 | {"{language}":"French"} -------------------------------------------------------------------------------- /test/prompts_dir/also_included.txt: -------------------------------------------------------------------------------- 1 | Hello Dolly! 2 | Well HELLO Freddy -------------------------------------------------------------------------------- /test/prompts_dir/test_prompt.json: -------------------------------------------------------------------------------- 1 | {"[SIZE]":[20],"[COLOR]":["blue"]} -------------------------------------------------------------------------------- /test/prompts_dir/test_prompt.txt: -------------------------------------------------------------------------------- 1 | This is a prompt with [SIZE] and [COLOR]. -------------------------------------------------------------------------------- /examples/prompts_dir/todo.json: -------------------------------------------------------------------------------- 1 | {"[LANGUAGE]":[],"[KEYWORD_AKA_TODO]":"TODO"} -------------------------------------------------------------------------------- /prompt_manager_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MadBomber/prompt_manager/HEAD/prompt_manager_logo.png -------------------------------------------------------------------------------- /lib/prompt_manager/version.rb: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | module PromptManager 4 | VERSION = "0.5.8" 5 | end 6 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | # Specify your gem's dependencies in prompt_manager.gemspec 4 | gemspec 5 | 6 | gem 'rake' 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.bundle/ 2 | /.yardoc 3 | /_yardoc/ 4 | /coverage/ 5 | /doc/ 6 | /pkg/ 7 | /spec/reports/ 8 | /tmp/ 9 | temp.md 10 | .aigcm_msg 11 | -------------------------------------------------------------------------------- /test/prompt_manager/storage_test.rb: -------------------------------------------------------------------------------- 1 | 2 | require 'test_helper' 3 | 4 | class StorageTest < Minitest::Test 5 | def test_dummy 6 | assert true 7 | end 8 | end 9 | -------------------------------------------------------------------------------- /test/prompts_dir/hello_prompt.txt: -------------------------------------------------------------------------------- 1 | # test/prompts_dir/hello_prompt.txt 2 | # Desc: This prompt says hello 3 | 4 | Hello, how are you? Are you ready to assist me with some research? 5 | -------------------------------------------------------------------------------- /test/prompts_dir/toy/8-ball.txt: -------------------------------------------------------------------------------- 1 | # prompt_manager/examples/prompts_dir/toy/8-ball.txt 2 | # Desc: In the late 1940s the toy "Magic 8 Ball" came to market 3 | 4 | As a magic 8-ball, provide me with a terse answer to what you suspect that I am thinking about. 5 | -------------------------------------------------------------------------------- /examples/prompts_dir/toy/8-ball.txt: -------------------------------------------------------------------------------- 1 | # prompt_manager/examples/prompts_dir/toy/8-ball.txt 2 | # Desc: In the late 1940s the toy "Magic 8 Ball" came to market 3 | 4 | As a magic 8-ball, provide me with a terse answer to what you suspect that I am thinking about. 5 | -------------------------------------------------------------------------------- /test/prompts_dir/test_parameters.txt: -------------------------------------------------------------------------------- 1 | # test/prompts_dir/test_parameters.txt 2 | # Desc: Test parameters for prompt manager 3 | 4 | default prompt regex: [PARAMETER] 5 | user supplied prompt regex: {{parameter two}} 6 | 7 | __END__ 8 | 9 | Testing both the default regex and the example user supplied 10 | regex. 11 | -------------------------------------------------------------------------------- /examples/prompts_dir/directive_example.txt: -------------------------------------------------------------------------------- 1 | # This is a demonstration of directive processing 2 | # Comments like this are ignored when the prompt is processed 3 | 4 | // good_directive param_one param_two 5 | 6 | This is a demonstration of parameters using {language} syntax. 7 | 8 | You can substitute parameters like {language} with values. 9 | -------------------------------------------------------------------------------- /test/prompts_dir/test_parameters_and_directives.txt: -------------------------------------------------------------------------------- 1 | # test/prompts_dir/test_parameters_and_directives.txt 2 | # Desc: Test parameters and directives for prompt manager 3 | 4 | //TextToSpeech [LANGUAGE] [VOICE NAME] 5 | 6 | //model gpt-5 7 | //include path_to_file 8 | 9 | Tell me a few [KIND] jokes about [SUBJECT] 10 | 11 | //[COMMAND] [OPTIONS] 12 | 13 | __END__ 14 | -------------------------------------------------------------------------------- /test/prompts_dir/test_directives.txt: -------------------------------------------------------------------------------- 1 | # test/prompts_dir/test_directives.txt 2 | # Desc: Test directives for prompt manager 3 | 4 | //TextToSpeech English Frank 5 | 6 | Say the lyrics to the song "My Way". Please provide only the lyrics without commentary. 7 | 8 | //model gpt-5 9 | //include path_to_file 10 | 11 | __END__ 12 | Computers will never replace Frank Sinatra 13 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | begin 4 | require "tocer/rake/register" 5 | rescue LoadError => error 6 | puts error.message 7 | end 8 | 9 | Tocer::Rake::Register.call 10 | 11 | require "bundler/gem_tasks" 12 | require "rake/testtask" 13 | 14 | Rake::TestTask.new(:test) do |t| 15 | t.libs << "test" 16 | t.libs << "lib" 17 | t.test_files = FileList["test/**/*_test.rb"] 18 | end 19 | 20 | task default: :test 21 | -------------------------------------------------------------------------------- /test/prompts_dir/todo.txt: -------------------------------------------------------------------------------- 1 | # prompts_dir/todo.txt 2 | # Desc: Let the robot fix the TODO items. 3 | # 4 | 5 | As an experienced [LANGUAGE] software engineer write some [LANGUAGE] source code. Consider the following [LANGUAGE] file. For each comment line that contains the word "[KEYWORD_AKA_TODO]" take the text that follows that word as a requirement to be implemented in [LANGUAGE]. Remove the "[KEYWORD_AKA_TODO]" word from the comment line. After the line insert the [LANGUAGE] code that implements the requirement. 6 | 7 | __END__ 8 | -------------------------------------------------------------------------------- /examples/prompts_dir/todo.txt: -------------------------------------------------------------------------------- 1 | # prompts_dir/todo.txt 2 | # Desc: Let the robot fix the TODO items. 3 | # 4 | 5 | As an experienced [LANGUAGE] software engineer write some [LANGUAGE] source code. Consider the following [LANGUAGE] file. For each comment line that contains the word "[KEYWORD_AKA_TODO]" take the text that follows that word as a requirement to be implemented in [LANGUAGE]. Remove the "[KEYWORD_AKA_TODO]" word from the comment line. After the line insert the [LANGUAGE] code that implements the requirement. 6 | 7 | __END__ 8 | -------------------------------------------------------------------------------- /.irbrc: -------------------------------------------------------------------------------- 1 | require_relative 'lib/prompt_manager' 2 | require_relative 'lib/prompt_manager/storage/file_system_adapter' 3 | 4 | HERE = Pathname.new __dir__ 5 | 6 | PromptManager::Storage::FileSystemAdapter.config do |config| 7 | config.prompts_dir = HERE + 'examples/prompts_dir' 8 | # config.search_proc = nil # default 9 | # config.prompt_extension = '.txt' # default 10 | # config.parms+_extension = '.json' # default 11 | end 12 | 13 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new 14 | 15 | -------------------------------------------------------------------------------- /test/prompt_manager_test.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/test/prompt_manager_test.rb 2 | 3 | require 'test_helper' 4 | 5 | class TestPromptManager < Minitest::Test 6 | def test_that_it_has_a_version_number 7 | refute_nil ::PromptManager::VERSION 8 | end 9 | 10 | def test_prompt_manager_error_handling_with_custom_error 11 | assert_raises(PromptManager::Error) do 12 | raise PromptManager::Error, "Custom error message" 13 | end 14 | end 15 | 16 | def test_prompt_manager_error_handling 17 | assert_raises(PromptManager::Error) do 18 | raise PromptManager::Error, "This is a test error" 19 | end 20 | end 21 | end 22 | 23 | __END__ 24 | 25 | -------------------------------------------------------------------------------- /test/test_helper.rb: -------------------------------------------------------------------------------- 1 | # test/test_helper.rb 2 | 3 | require 'simplecov' 4 | SimpleCov.start do 5 | add_filter '/test/' 6 | end 7 | 8 | require 'debug_me' 9 | include DebugMe 10 | 11 | require 'pathname' 12 | 13 | # Add the gem's lib directory to the load path 14 | $LOAD_PATH.unshift File.expand_path("../lib", __dir__) 15 | 16 | # Define test directory and prompts directory 17 | $TEST_DIR = Pathname.new(__dir__) 18 | $PROMPTS_DIR = $TEST_DIR.join("prompts_dir") 19 | 20 | require "prompt_manager" 21 | 22 | # All non-storage tests are going to use the FileSystemAdapter 23 | PromptManager::Prompt 24 | .storage_adapter = 25 | PromptManager::Storage::FileSystemAdapter 26 | .config do |config| 27 | config.prompts_dir = $PROMPTS_DIR 28 | end.new 29 | 30 | require "minitest/autorun" 31 | require 'minitest/pride' 32 | -------------------------------------------------------------------------------- /.github/workflows/docs.yml: -------------------------------------------------------------------------------- 1 | name: Deploy Documentation 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | paths: 8 | - 'docs/**' 9 | - 'mkdocs.yml' 10 | - '.github/workflows/docs.yml' 11 | workflow_dispatch: 12 | 13 | permissions: 14 | contents: write 15 | pages: write 16 | id-token: write 17 | 18 | jobs: 19 | deploy: 20 | runs-on: ubuntu-latest 21 | steps: 22 | - name: Checkout repository 23 | uses: actions/checkout@v4 24 | with: 25 | fetch-depth: 0 26 | 27 | - name: Set up Python 28 | uses: actions/setup-python@v4 29 | with: 30 | python-version: '3.11' 31 | 32 | - name: Install Python dependencies 33 | run: | 34 | python -m pip install --upgrade pip 35 | pip install mkdocs-material mkdocs-minify-plugin 36 | 37 | - name: Deploy to GitHub Pages 38 | run: mkdocs gh-deploy --force -------------------------------------------------------------------------------- /docs/core-features/directive-processing.md: -------------------------------------------------------------------------------- 1 | # Directive Processing 2 | 3 | Directives are special instructions in your prompts that begin with `//` and provide powerful prompt composition capabilities. 4 | 5 | ## Overview 6 | 7 | Directives allow you to: 8 | - Include content from other files 9 | - Create modular, reusable prompt components 10 | - Build dynamic prompt structures 11 | - Process commands during prompt generation 12 | 13 | ## Built-in Directives 14 | 15 | ### `//include` (alias: `//import`) 16 | 17 | Include content from other files: 18 | 19 | ```text 20 | //include common/header.txt 21 | //import templates/[TEMPLATE_TYPE].txt 22 | 23 | Your main prompt content here... 24 | ``` 25 | 26 | ## Example 27 | 28 | ```text title="customer_response.txt" 29 | //include common/header.txt 30 | 31 | Dear [CUSTOMER_NAME], 32 | 33 | Thank you for your inquiry about [TOPIC]. 34 | 35 | //include common/footer.txt 36 | ``` 37 | 38 | For detailed examples and advanced usage, see the [Basic Examples](../examples/basic.md). -------------------------------------------------------------------------------- /lib/prompt_manager.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/lib/prompt_manager.rb 2 | # 3 | # frozen_string_literal: true 4 | 5 | require 'ostruct' 6 | 7 | require_relative "prompt_manager/version" 8 | require_relative "prompt_manager/prompt" 9 | require_relative "prompt_manager/storage" 10 | require_relative "prompt_manager/storage/file_system_adapter" 11 | 12 | # The PromptManager module provides functionality for managing, storing, 13 | # retrieving, and parameterizing text prompts used with generative AI systems. 14 | # It supports different storage backends through adapters and offers features 15 | # like parameter substitution, directives processing, and comment handling. 16 | module PromptManager 17 | # Base error class for all PromptManager-specific errors 18 | class Error < StandardError; end 19 | 20 | # Error class for storage-related issues 21 | class StorageError < Error; end 22 | 23 | # Error class for parameter substitution issues 24 | class ParameterError < Error; end 25 | 26 | # Error class for configuration issues 27 | class ConfigurationError < Error; end 28 | end 29 | -------------------------------------------------------------------------------- /test/test_prompt_features.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | require 'minitest/autorun' 3 | require_relative '../lib/prompt_manager/prompt' 4 | 5 | class TestPromptFeatures < Minitest::Test 6 | def setup 7 | @original_env = ENV.to_hash 8 | end 9 | 10 | def teardown 11 | ENV.replace(@original_env) 12 | end 13 | 14 | def test_env_variable_replacement 15 | ENV['GREETING'] = 'Hello' 16 | prompt_text = 'Say $GREETING to world!' 17 | prompt = PromptManager::Prompt.new(prompt_text) 18 | result = prompt.process 19 | assert_equal 'Say Hello to world!', result 20 | end 21 | 22 | def test_erb_processing 23 | prompt_text = '2+2 is <%= 2+2 %>' 24 | prompt = PromptManager::Prompt.new(prompt_text) 25 | result = prompt.process 26 | assert_equal '2+2 is 4', result 27 | end 28 | 29 | def test_combined_features 30 | ENV['NAME'] = 'Alice' 31 | prompt_text = 'Hi, $NAME! Today, 3*3 equals <%= 3*3 %>.' 32 | prompt = PromptManager::Prompt.new(prompt_text) 33 | result = prompt.process 34 | assert_equal 'Hi, Alice! Today, 3*3 equals 9.', result 35 | end 36 | end 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Dewayne VanHoozer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /docs/core-features/comments.md: -------------------------------------------------------------------------------- 1 | # Comments and Documentation 2 | 3 | PromptManager supports comprehensive inline documentation through comments and special sections. 4 | 5 | ## Line Comments 6 | 7 | Lines beginning with `#` are treated as comments and ignored during processing: 8 | 9 | ```text 10 | # This is a comment describing the prompt 11 | # Author: Your Name 12 | # Version: 1.0 13 | 14 | Hello [NAME]! This text will be processed. 15 | ``` 16 | 17 | ## Block Comments 18 | 19 | Everything after `__END__` is ignored, creating a documentation section: 20 | 21 | ```text 22 | Your prompt content here... 23 | 24 | __END__ 25 | This section is completely ignored by PromptManager. 26 | 27 | Development notes: 28 | - TODO: Add more parameters 29 | - Version history 30 | - Usage examples 31 | ``` 32 | 33 | ## Documentation Best Practices 34 | 35 | ```text 36 | # Description: Customer service greeting template 37 | # Tags: customer-service, greeting 38 | # Version: 1.2 39 | # Author: Support Team 40 | # Last Updated: 2024-01-15 41 | 42 | //include common/header.txt 43 | 44 | Your prompt content... 45 | 46 | __END__ 47 | Internal notes and documentation go here. 48 | ``` -------------------------------------------------------------------------------- /docs/assets/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | -------------------------------------------------------------------------------- /examples/advanced_integrations.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # frozen_string_literal: true 3 | 4 | require 'bundler/inline' 5 | 6 | gemfile do 7 | source 'https://rubygems.org' 8 | gem 'prompt_manager' 9 | gem 'ruby-openai' 10 | gem 'tty-spinner' 11 | end 12 | 13 | require 'prompt_manager' 14 | require 'openai' 15 | require 'erb' 16 | require 'time' 17 | require 'tty-spinner' 18 | 19 | # Configure PromptManager with filesystem adapter 20 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.config do |config| 21 | config.prompts_dir = File.join(__dir__, 'prompts_dir') 22 | end.new 23 | 24 | # Configure OpenAI client 25 | client = OpenAI::Client.new( 26 | access_token: ENV['OPENAI_API_KEY'] 27 | ) 28 | 29 | # Get prompt instance and process with LLM 30 | prompt = PromptManager::Prompt.new( 31 | id: 'advanced_demo', 32 | erb_flag: true, 33 | envar_flag: true 34 | ) 35 | 36 | spinner = TTY::Spinner.new("[:spinner] Waiting for response...") 37 | spinner.auto_spin 38 | 39 | response = client.chat( 40 | parameters: { 41 | model: 'gpt-4o-mini', 42 | messages: [{ role: 'user', content: prompt.to_s }], 43 | stream: proc do |chunk, _bytesize| 44 | spinner.stop 45 | content = chunk.dig("choices", 0, "delta", "content") 46 | print content if content 47 | $stdout.flush 48 | end 49 | } 50 | ) 51 | 52 | puts 53 | -------------------------------------------------------------------------------- /examples/rgfzf: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | # Refactored examples/rgfzf to take search term and directory path as parameters 3 | 4 | search_term="$1" 5 | directory_path="${2:-$(pwd)}" # Use given directory path, or current working directory if not provided 6 | 7 | # Verify that a search term is provided 8 | if [[ -z "$search_term" ]]; then 9 | echo "Usage: $0 search_term [directory_path]" 10 | exit 1 11 | fi 12 | 13 | # Ensure ripgrep (rg) and fzf are installed 14 | if ! command -v rg &> /dev/null || ! command -v fzf &> /dev/null; then 15 | echo "Please ensure ripgrep and fzf are installed before running this script." 16 | exit 1 17 | fi 18 | 19 | # Perform the file search using ripgrep and selection using fzf 20 | selected_file=$( 21 | rg --files-with-matches \ 22 | --no-messages \ 23 | --smart-case "$search_term" "$directory_path" | 24 | sed "s#^$directory_path/##" | # Strip out the directory path 25 | fzf --ansi \ 26 | --color "hl:-1:underline,hl+:-1:underline:reverse" \ 27 | --preview "cat $directory_path/{}" \ 28 | --preview-window "up,60%,border-bottom" \ 29 | --no-multi \ 30 | --exit-0 \ 31 | --query "$search_term" 32 | ) 33 | 34 | 35 | # If no file was selected, exit the script 36 | if [[ -z "$selected_file" ]]; then 37 | # echo "No file selected." 38 | exit 0 39 | fi 40 | 41 | # Remove the file extension 42 | prompt_id=$(echo "$selected_file" | sed "s/\.[^.]*$//") 43 | 44 | echo "$prompt_id" 45 | -------------------------------------------------------------------------------- /lib/prompt_manager/directive_processor.rb: -------------------------------------------------------------------------------- 1 | # lib/prompt_manager/directive_processor.rb 2 | 3 | # This is an example of a directive processor class. 4 | # It only supports the //include directive which is also 5 | # aliased as //import. 6 | 7 | module PromptManager 8 | class DirectiveProcessor 9 | EXCLUDED_METHODS = %w[ run initialize ] 10 | 11 | def initialize 12 | @prefix_size = PromptManager::Prompt::DIRECTIVE_SIGNAL.size 13 | @included_files = [] 14 | end 15 | 16 | def run(directives) 17 | return {} if directives.nil? || directives.empty? 18 | directives.each do |key, _| 19 | sans_prefix = key[@prefix_size..] 20 | args = sans_prefix.split(' ') 21 | method_name = args.shift 22 | 23 | if EXCLUDED_METHODS.include?(method_name) 24 | directives[key] = "Error: #{method_name} is not a valid directive: #{key}" 25 | elsif respond_to?(method_name) 26 | directives[key] = send(method_name, *args) 27 | else 28 | directives[key] = "Error: Unknown directive '#{key}'" 29 | end 30 | end 31 | directives 32 | end 33 | 34 | def include(file_path) 35 | if File.exist?(file_path) && 36 | File.readable?(file_path) && 37 | !@included_files.include?(file_path) 38 | content = File.read(file_path) 39 | @included_files << file_path 40 | content 41 | else 42 | "Error: File '#{file_path}' not accessible" 43 | end 44 | end 45 | alias_method :import, :include 46 | end 47 | end 48 | -------------------------------------------------------------------------------- /lib/prompt_manager/storage.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/lib/prompt_manager/storage.rb 2 | 3 | # The Storage module provides a namespace for different storage adapters 4 | # that handle persistence of prompts. Each adapter implements a common 5 | # interface for saving, retrieving, searching, and deleting prompts. 6 | # 7 | # Available adapters: 8 | # - FileSystemAdapter: Stores prompts in text files on the local filesystem 9 | # - ActiveRecordAdapter: Stores prompts in a database using ActiveRecord 10 | # 11 | # To use an adapter, configure it before using PromptManager:: 12 | # 13 | # Example with FileSystemAdapter: 14 | # PromptManager::Storage::FileSystemAdapter.config do |config| 15 | # config.prompts_dir = Pathname.new('/path/to/prompts') 16 | # end 17 | # PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new 18 | # 19 | # Example with ActiveRecordAdapter: 20 | # PromptManager::Storage::ActiveRecordAdapter.config do |config| 21 | # config.model = MyPromptModel 22 | # config.id_column = :prompt_id 23 | # config.text_column = :content 24 | # config.parameters_column = :params 25 | # end 26 | # PromptManager::Prompt.storage_adapter = PromptManager::Storage::ActiveRecordAdapter.new 27 | module PromptManager 28 | # The Storage module provides adapters for different storage backends. 29 | # Each adapter implements a common interface for managing prompts. 30 | # Note: PromptManager::Prompt uses one of these adapters as its storage backend to 31 | # perform all CRUD operations on prompt data. 32 | module Storage 33 | end 34 | end 35 | -------------------------------------------------------------------------------- /test/prompt_manager/directive_processor_test.rb: -------------------------------------------------------------------------------- 1 | # test/prompt_manager/directive_processor_test.rb 2 | 3 | require 'test_helper' 4 | require 'tempfile' 5 | 6 | class DirectiveProcessorTest < Minitest::Test 7 | def setup 8 | @processor = PromptManager::DirectiveProcessor.new 9 | end 10 | 11 | def test_run_with_nil_or_empty 12 | assert_equal({}, @processor.run(nil)) 13 | assert_equal({}, @processor.run({})) 14 | end 15 | 16 | def test_run_with_excluded_method 17 | directives = { "//run something" => "" } 18 | result = @processor.run(directives) 19 | expected = "Error: run is not a valid directive: //run something" 20 | 21 | assert_equal expected, result["//run something"] 22 | end 23 | 24 | def test_run_with_unknown_directive 25 | directives = { "//unknown parameter" => "" } 26 | result = @processor.run(directives) 27 | expected = "Error: Unknown directive '//unknown parameter'" 28 | assert_equal expected, result["//unknown parameter"] 29 | end 30 | 31 | def test_run_include_with_nonexistent_file 32 | directives = { "//include /path/to/nonexistent_file.txt" => "" } 33 | result = @processor.run(directives) 34 | expected = "Error: File '/path/to/nonexistent_file.txt' not accessible" 35 | 36 | assert_equal expected, result["//include /path/to/nonexistent_file.txt"] 37 | end 38 | 39 | def test_alias_import_for_include 40 | directives = { "//import /path/to/nonexistent_file.txt" => "" } 41 | result = @processor.run(directives) 42 | expected = "Error: File '/path/to/nonexistent_file.txt' not accessible" 43 | 44 | assert_equal expected, result["//import /path/to/nonexistent_file.txt"] 45 | end 46 | end 47 | -------------------------------------------------------------------------------- /prompt_manager.gemspec: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | require_relative "lib/prompt_manager/version" 4 | 5 | Gem::Specification.new do |spec| 6 | spec.name = "prompt_manager" 7 | spec.version = PromptManager::VERSION 8 | spec.authors = ["Dewayne VanHoozer"] 9 | spec.email = ["dvanhoozer@gmail.com"] 10 | 11 | spec.summary = "Manage prompts for use with gen-AI processes" 12 | 13 | spec.description = <<~EOS 14 | Manage the parameterized prompts (text) used in generative AI (aka chatGPT, 15 | OpenAI, et.al.) using storage adapters such as FileSystemAdapter, 16 | SqliteAdapter, and ActiveRecordAdapter. 17 | EOS 18 | 19 | spec.homepage = "https://github.com/MadBomber/prompt_manager" 20 | spec.license = "MIT" 21 | 22 | spec.required_ruby_version = ">= 3.2.0" 23 | 24 | spec.metadata["allowed_push_host"] = "https://rubygems.org" 25 | spec.metadata["homepage_uri"] = spec.homepage 26 | spec.metadata["source_code_uri"] = spec.homepage 27 | spec.metadata["changelog_uri"] = spec.homepage 28 | 29 | spec.files = Dir.chdir(__dir__) do 30 | `git ls-files -z`.split("\x0").reject do |f| 31 | (File.expand_path(f) == __FILE__) || 32 | f.start_with?(*%w[test/ spec/ features/ .git appveyor Gemfile]) 33 | end 34 | end 35 | 36 | spec.require_paths = ["lib"] 37 | 38 | spec.add_development_dependency 'activerecord' 39 | spec.add_development_dependency 'amazing_print' 40 | spec.add_development_dependency 'debug_me' 41 | spec.add_development_dependency "minitest" 42 | spec.add_development_dependency "ostruct" 43 | spec.add_development_dependency 'tocer' 44 | spec.add_development_dependency 'simplecov' 45 | spec.add_development_dependency 'sqlite3' 46 | 47 | 48 | # Add runtime dependencies if necessary 49 | # spec.add_dependency "some_runtime_dependency" 50 | end -------------------------------------------------------------------------------- /docs/assets/favicon.ico: -------------------------------------------------------------------------------- 1 | data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAQAABILAAASCwAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A4uLiDOHh4Rjh4eEY4eHhGOHh4Rjh4eEY4eHhGOHh4Rji4uIM////AP///wD///8A////AP///wDY2NgspqamjJmZmbeZmZm3mZmZt5mZmbeZmZm3mZmZt5mZmbeZmZm3pqamjNjY2Cz///8A////AP///wCfn5+MZGRk/1FRUX9RUVF/UVFRX1FRUX9RUVF/UVFRX1FRUX9RUVF/UVFRX2RkZP+fn5+M////AP///wCWlpa3UFBQ/4CAgP+BgYH/gYGB/4GBgf+BgYH/gYGB/4GBgf+BgYH/gYGB/4CAgP9QUFD/lpaWt////wCWlpa3UFBQ/4CAgP//////////////////////////////////////////////////////////////////////////////////////gICA/1BQUP+Wlpa3////AJaWlrdQUFD/gICA//////////////////////////////////////////////////7+/v/+/v7//v7+/v+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////X19f/Ozs7/zs7O/87Ozv/Ozs7/9fX1///////////////////////AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////X19f/Ozs7/////////////////zs7O/87Ozv/19fX///////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////X19f/Ozs7/zs7O/87Ozv/Ozs7/zs7O/87Ozv/19fX///////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////X19f/Ozs7/////////////////zs7O/87Ozv/19fX///////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////X19f/Ozs7/zs7O/87Ozv/Ozs7/zs7O/87Ozv/19fX///////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////////////////////7+/v/+/v7//v7+/v////////////////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID///////////////////////////////////////////////////////////////////////////////////////+AgID/UFBQ/5aWlrf///8AlpaWt1BQUP+AgID/gYGB/4GBgf+BgYH/gYGB/4GBgf+BgYH/gYGB/4GBgf+BgYH/gICA/1BQUP+Wlpa3////AJ+fn4xkZGT/UVFRX1FRUX9RUVF/UVFRX1FRUX9RUVF/UVFRX1FRUX9RUVF/UVFRX2RkZP+fn5+M////AP///wDY2NgspqamjJmZmbeZmZm3mZmZt5mZmbeZmZm3mZmZt5mZmbeZmZm3pqamjNjY2Cz///8A////AP///wD///8A////AP///wDi4uIM4eHhGOHh4Rjh4eEY4eHhGOHh4Rjh4eEY4eHhGOLi4gz///8A////AP///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wA= -------------------------------------------------------------------------------- /examples/using_search_proc.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # encoding: utf-8 3 | # frozen_string_literal: true 4 | # warn_indent: true 5 | ########################################################## 6 | ### 7 | ## File: using_search_proc.rb 8 | ## Desc: Simple demo of the PromptManager and FileStorageAdapter 9 | ## By: Dewayne VanHoozer (dvanhoozer@gmail.com) 10 | ## 11 | # 12 | 13 | require 'prompt_manager' 14 | require 'prompt_manager/storage/file_system_adapter' 15 | 16 | require 'amazing_print' 17 | require 'pathname' 18 | 19 | HERE = Pathname.new( __dir__ ) 20 | PROMPTS_DIR = HERE + "prompts_dir" 21 | SEARCH_SCRIPT = HERE + 'rgfzf' # a bash script using rg and fzf 22 | 23 | ###################################################### 24 | # Main 25 | 26 | at_exit do 27 | puts 28 | puts "Done." 29 | puts 30 | end 31 | 32 | # Configure the Storage Adapter to use 33 | PromptManager::Storage::FileSystemAdapter.config do |config| 34 | config.prompts_dir = PROMPTS_DIR 35 | config.search_proc = ->(q) {`#{SEARCH_SCRIPT} #{q} #{PROMPTS_DIR}`} # default 36 | # config.prompt_extension = '.txt' # default 37 | # config.parms+_extension = '.json' # default 38 | end 39 | 40 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new 41 | 42 | 43 | 44 | puts "Using Custom Search Proc" 45 | puts "========================" 46 | 47 | print "Search Proc Class: " 48 | puts PromptManager::Prompt.storage_adapter.search_proc.class 49 | 50 | search_term = "txt" # some comment lines show the file name example: todo.txt 51 | 52 | puts "Search for '#{search_term}' ..." 53 | 54 | prompt_id = PromptManager::Prompt.search search_term 55 | 56 | # NOTE: the search proc uses fzf as a selection tool. In this 57 | # case only one selected prompt ID that matches the search 58 | # term will be returned. 59 | 60 | puts "Found: '#{prompt_id}' which is a #{prompt_id.class}. empty? #{prompt_id.empty?}" 61 | 62 | puts <<~EOS 63 | 64 | When the rgfzf bash script does not find a prompt ID or if the 65 | ESC key is pressed, the prompt ID that is returned will be an empty String. 66 | 67 | EOS 68 | 69 | -------------------------------------------------------------------------------- /docs/core-features/erb-integration.md: -------------------------------------------------------------------------------- 1 | # ERB Integration 2 | 3 | PromptManager supports ERB (Embedded Ruby) templating for dynamic content generation. 4 | 5 | ## Enabling ERB 6 | 7 | ```ruby 8 | prompt = PromptManager::Prompt.new( 9 | id: 'dynamic_prompt', 10 | erb_flag: true 11 | ) 12 | ``` 13 | 14 | ## Basic Usage 15 | 16 | ```text title="dynamic_prompt.txt" 17 | Current date: <%= Date.today.strftime('%B %d, %Y') %> 18 | 19 | <% if '[PRIORITY]' == 'high' %> 20 | 🚨 URGENT: This requires immediate attention! 21 | <% else %> 22 | 📋 Standard processing request. 23 | <% end %> 24 | 25 | Generated at: <%= Time.now %> 26 | ``` 27 | 28 | ## Advanced Examples 29 | 30 | ### System Information Template 31 | 32 | ```text 33 | **Timestamp**: <%= Time.now.strftime('%A, %B %d, %Y at %I:%M:%S %p %Z') %> 34 | **Analysis Duration**: <%= Time.now - Time.parse('2024-01-01') %> seconds since 2024 began 35 | 36 | <% if RUBY_PLATFORM.include?('darwin') %> 37 | **Platform**: macOS/Darwin System 38 | **Ruby Platform**: <%= RUBY_PLATFORM %> 39 | **Ruby Version**: <%= RUBY_VERSION %> 40 | **Ruby Engine**: <%= RUBY_ENGINE %> 41 | <% elsif RUBY_PLATFORM.include?('linux') %> 42 | **Platform**: Linux System 43 | **Ruby Platform**: <%= RUBY_PLATFORM %> 44 | **Ruby Version**: <%= RUBY_VERSION %> 45 | **Ruby Engine**: <%= RUBY_ENGINE %> 46 | <% else %> 47 | **Platform**: Other Unix-like System 48 | **Ruby Platform**: <%= RUBY_PLATFORM %> 49 | **Ruby Version**: <%= RUBY_VERSION %> 50 | **Ruby Engine**: <%= RUBY_ENGINE %> 51 | <% end %> 52 | 53 | **Performance Context**: <%= `uptime`.strip rescue 'Unable to determine' %> 54 | ``` 55 | 56 | ### Complete Integration Example 57 | 58 | See the complete [advanced_integrations.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/advanced_integrations.rb) example that demonstrates: 59 | 60 | - ERB templating with system information 61 | - Dynamic timestamp generation 62 | - Platform-specific content rendering 63 | - Integration with OpenAI API streaming 64 | - Professional UI with `tty-spinner` 65 | 66 | This example shows how to create sophisticated prompts that adapt to your system environment and generate technical analysis reports. 67 | 68 | For more comprehensive ERB examples, see the [Examples documentation](../examples.md). -------------------------------------------------------------------------------- /docs/getting-started/installation.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | ## System Requirements 4 | 5 | PromptManager requires: 6 | 7 | - **Ruby**: 2.7 or higher (3.0+ recommended) 8 | - **Operating System**: Linux, macOS, or Windows 9 | - **Dependencies**: No additional system dependencies required 10 | 11 | ## Install the Gem 12 | 13 | ### Using Bundler (Recommended) 14 | 15 | Add PromptManager to your project's `Gemfile`: 16 | 17 | ```ruby 18 | # Gemfile 19 | gem 'prompt_manager' 20 | ``` 21 | 22 | Then install: 23 | 24 | ```bash 25 | bundle install 26 | ``` 27 | 28 | ### Using RubyGems 29 | 30 | Install directly with gem: 31 | 32 | ```bash 33 | gem install prompt_manager 34 | ``` 35 | 36 | ### Development Installation 37 | 38 | For development or to get the latest features: 39 | 40 | ```bash 41 | git clone https://github.com/MadBomber/prompt_manager.git 42 | cd prompt_manager 43 | bundle install 44 | ``` 45 | 46 | ## Verify Installation 47 | 48 | Test that PromptManager is installed correctly: 49 | 50 | ```ruby 51 | require 'prompt_manager' 52 | puts PromptManager::VERSION 53 | ``` 54 | 55 | ## Dependencies 56 | 57 | PromptManager has minimal dependencies and automatically installs: 58 | 59 | - **No external system dependencies** 60 | - **Pure Ruby dependencies** only 61 | - **Lightweight footprint** for easy integration 62 | 63 | ## Troubleshooting 64 | 65 | ### Common Issues 66 | 67 | !!! warning "Ruby Version" 68 | 69 | If you see compatibility errors, ensure you're running Ruby 2.7+: 70 | 71 | ```bash 72 | ruby --version 73 | ``` 74 | 75 | !!! tip "Bundler Issues" 76 | 77 | If bundle install fails, try updating bundler: 78 | 79 | ```bash 80 | gem update bundler 81 | bundle install 82 | ``` 83 | 84 | ### Getting Help 85 | 86 | If you encounter installation issues: 87 | 88 | 1. Check the [GitHub Issues](https://github.com/MadBomber/prompt_manager/issues) 89 | 2. Search for similar problems in [Discussions](https://github.com/MadBomber/prompt_manager/discussions) 90 | 3. Create a new issue with: 91 | - Ruby version (`ruby --version`) 92 | - Gem version (`gem list prompt_manager`) 93 | - Error message and full stack trace 94 | 95 | ## Next Steps 96 | 97 | Once installed, continue to the [Quick Start](quick-start.md) guide to begin using PromptManager. -------------------------------------------------------------------------------- /docs/core-features/shell-integration.md: -------------------------------------------------------------------------------- 1 | # Shell Integration 2 | 3 | PromptManager can automatically substitute environment variables and integrate with shell commands. 4 | 5 | ## Environment Variables 6 | 7 | Enable environment variable substitution: 8 | 9 | ```ruby 10 | prompt = PromptManager::Prompt.new( 11 | id: 'system_prompt', 12 | envar_flag: true 13 | ) 14 | ``` 15 | 16 | Environment variables in your prompt text will be automatically replaced. 17 | 18 | ## Example 19 | 20 | ```text title="system_prompt.txt" 21 | System: $USER 22 | Home: $HOME 23 | Path: $PATH 24 | 25 | Working directory: <%= Dir.pwd %> 26 | ``` 27 | 28 | ## Shell Command Execution 29 | 30 | PromptManager also supports shell command substitution using `$(command)` syntax: 31 | 32 | ```text title="system_info.txt" 33 | Current system load: $(uptime) 34 | Disk usage: $(df -h / | tail -1) 35 | Memory info: $(vm_stat | head -5) 36 | ``` 37 | 38 | Commands are executed when the prompt is processed, with output substituted in place. 39 | 40 | ## Advanced Example 41 | 42 | The [advanced_integrations.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/advanced_integrations.rb) example demonstrates comprehensive shell integration: 43 | 44 | ```text 45 | ### Hardware Platform Details 46 | **Architecture**: $HOSTTYPE$MACHTYPE 47 | **Hostname**: $HOSTNAME 48 | **Operating System**: $OSTYPE 49 | **Shell**: $SHELL (version: $BASH_VERSION) 50 | **User**: $USER 51 | **Home Directory**: $HOME 52 | **Current Path**: $PWD 53 | **Terminal**: $TERM 54 | 55 | ### Environment Configuration 56 | **PATH**: $PATH 57 | **Language**: $LANG 58 | **Editor**: $EDITOR 59 | **Pager**: $PAGER 60 | 61 | ### Performance Context 62 | **Load Average**: <%= `uptime`.strip rescue 'Unable to determine' %> 63 | **Memory Info**: <%= `vm_stat | head -5`.strip rescue 'Unable to determine' if RUBY_PLATFORM.include?('darwin') %> 64 | **Disk Usage**: <%= `df -h / | tail -1`.strip rescue 'Unable to determine' %> 65 | ``` 66 | 67 | This creates dynamic prompts that capture real-time system information for analysis. 68 | 69 | ## Configuration 70 | 71 | Set environment variables that your prompts will use: 72 | 73 | ```bash 74 | export API_KEY="your-api-key" 75 | export ENVIRONMENT="production" 76 | export OPENAI_API_KEY="your-openai-key" 77 | ``` 78 | 79 | For more shell integration examples, see the [Examples documentation](../examples.md). -------------------------------------------------------------------------------- /docs/core-features/parameter-history.md: -------------------------------------------------------------------------------- 1 | # Parameter History 2 | 3 | PromptManager automatically tracks parameter usage history to help you reuse previously entered values and maintain consistency across prompt executions. 4 | 5 | ## Automatic History Tracking 6 | 7 | When you use parameters in your prompts, PromptManager automatically saves the values you provide: 8 | 9 | ```ruby 10 | prompt = PromptManager::Prompt.new(id: 'customer_email') 11 | result = prompt.render(customer_name: 'John Doe', product: 'Pro Plan') 12 | # These values are automatically saved to history 13 | ``` 14 | 15 | ## History File Location 16 | 17 | Parameter history is stored in `~/.prompt_manager/parameters_history.yaml` by default. 18 | 19 | ## Accessing History 20 | 21 | Previous parameter values are automatically suggested when you use the same parameter names in subsequent prompts: 22 | 23 | ```ruby 24 | # First time - you provide values 25 | prompt.render(api_key: 'sk-123', model: 'gpt-4') 26 | 27 | # Second time - previous values are available 28 | prompt.render # Will suggest previously used api_key and model values 29 | ``` 30 | 31 | ## History Management 32 | 33 | ### Viewing History 34 | 35 | ```ruby 36 | # Access stored parameter values 37 | history = PromptManager.configuration.parameter_history 38 | puts history['api_key'] # Shows previously used API keys 39 | ``` 40 | 41 | ### Clearing History 42 | 43 | ```ruby 44 | # Clear all parameter history 45 | PromptManager.configuration.clear_parameter_history 46 | 47 | # Clear specific parameter 48 | PromptManager.configuration.clear_parameter('api_key') 49 | ``` 50 | 51 | ## Configuration 52 | 53 | Configure history behavior in your application: 54 | 55 | ```ruby 56 | PromptManager.configure do |config| 57 | config.save_parameter_history = true # Enable/disable history (default: true) 58 | config.parameter_history_file = 'custom_history.yaml' # Custom file location 59 | config.max_history_entries = 10 # Limit stored values per parameter 60 | end 61 | ``` 62 | 63 | ## Privacy Considerations 64 | 65 | Parameter history is stored locally and never transmitted. However, be mindful of sensitive data: 66 | 67 | - API keys and tokens are stored in plain text 68 | - Consider clearing history for sensitive parameters 69 | - Use environment variables for truly sensitive data instead of parameter history 70 | 71 | ## Best Practices 72 | 73 | 1. **Regular Cleanup**: Periodically clear old parameter values 74 | 2. **Sensitive Data**: Don't rely on history for secrets - use environment variables 75 | 3. **Team Sharing**: History files are user-specific, not shared across team members 76 | 4. **Backup**: Consider backing up important parameter configurations -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## Unreleased 2 | 3 | ## Released 4 | ### [0.5.8] = 2025-09-01 5 | - fixed issue where removed keywords from prompt text were still being included in parameters if they existed in the JSON file (addresses AIA issue #105) 6 | - parameters now only include keywords currently present in the prompt text, while preserving historical values for existing keywords 7 | 8 | ### [0.5.7] = 2025-06-25 9 | - fixed a problem when the value of a parameter is an empty array 10 | - fixed a failing test 11 | 12 | ### [0.5.6] = 2025-06-04 13 | - fixed a problem where shell integration was not working correctly for $(shell command) 14 | 15 | ### [0.5.5] = 2025-05-21 16 | - fixed bug in parameter substitution when value is an Array now uses last entry 17 | 18 | ### [0.5.4] = 2025-05-18 19 | - fixed typo in the Prompt class envvar should have been envar which prevented shell integration from taking place. 20 | 21 | ### [0.5.3] = 2025-05-14 22 | - fixed issue were directives were not getting their content added to the prompt text 23 | - Updated documentation and versioning. 24 | - Added new error classes for better error handling. 25 | - Improved parameter handling and directive processing. 26 | 27 | ### [0.5.0] = 2025-03-29 28 | - Major refactoring of to improve processing of parameters and directives. 29 | - Added PromptManager::DirectiveProcessor as an example of how to implement custom directives. 30 | - Added support for //include directive that protects against loops. 31 | - Added support for embedding system environment variables. 32 | - Added support for ERB processing within a prompt. 33 | - Improved test coverage. 34 | 35 | ### [0.4.2] = 2024-10-26 36 | - Added configurable parameter_regex to customize keyword pattern 37 | 38 | ### [0.4.1] = 2023-12-29 39 | - Changed @directives from Hash to an Array 40 | - Fixed keywords not being substituted in directives 41 | 42 | ### [0.4.0] = 2023-12-19 43 | - Add "//directives param(s)" with keywords just like the prompt text. 44 | 45 | ### [0.3.3] = 2023-12-01 46 | - Added example of using the `search_proc` config parameter with the FileSystemAdapter. 47 | 48 | ### [0.3.2] = 2023-12-01 49 | 50 | - The ActiveRecordAdapter is passing its unit tests 51 | - Dropped the concept of an sqlite3 adapter since active record can be used to access sqlite3 databases as well as the big boys. 52 | 53 | ### [0.3.0] = 2023-11-28 54 | 55 | - **Breaking change** 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 56 | 57 | ### [0.2.0] - 2023-11-21 58 | 59 | - **Breaking change to FileSystemAdapter config process** 60 | - added list and path as extra methods in FileSystemAdapter 61 | 62 | ### [0.1.0] - 2023-11-16 63 | 64 | - Initial release using the FileSystemAdapter 65 | -------------------------------------------------------------------------------- /test/prompt_manager/storage/test_removed_keywords_bug.rb: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | require_relative '../../test_helper' 4 | 5 | class TestRemovedKeywordsBug < Minitest::Test 6 | def setup 7 | @temp_dir = Dir.mktmpdir 8 | @adapter = PromptManager::Storage::FileSystemAdapter.config do |config| 9 | config.prompts_dir = @temp_dir 10 | end.new 11 | 12 | PromptManager::Prompt.storage_adapter = @adapter 13 | end 14 | 15 | def teardown 16 | FileUtils.remove_entry(@temp_dir) if @temp_dir && Dir.exist?(@temp_dir) 17 | end 18 | 19 | def test_removed_keywords_are_not_included_in_parameters 20 | prompt_id = 'test_prompt' 21 | 22 | # Step 1: Create a prompt with two keywords 23 | initial_text = "Hello [NAME], you are [AGE] years old." 24 | File.write(File.join(@temp_dir, "#{prompt_id}.txt"), initial_text) 25 | 26 | # Step 2: Save parameters for both keywords (simulating previous usage) 27 | params = { 28 | "[NAME]" => ["Alice", "Bob"], 29 | "[AGE]" => ["25", "30"] 30 | } 31 | File.write( 32 | File.join(@temp_dir, "#{prompt_id}.json"), 33 | JSON.pretty_generate(params) 34 | ) 35 | 36 | # Step 3: Update prompt text to remove [AGE] keyword 37 | updated_text = "Hello [NAME], welcome!" 38 | File.write(File.join(@temp_dir, "#{prompt_id}.txt"), updated_text) 39 | 40 | # Step 4: Load the prompt and check parameters 41 | prompt = PromptManager::Prompt.new(id: prompt_id) 42 | 43 | # The parameters should only include [NAME], not [AGE] 44 | assert_includes prompt.parameters.keys, "[NAME]" 45 | refute_includes prompt.parameters.keys, "[AGE]", 46 | "Removed keyword [AGE] should not be in parameters" 47 | 48 | # Verify the historical values are preserved for existing keywords 49 | assert_equal ["Alice", "Bob"], prompt.parameters["[NAME]"] 50 | end 51 | 52 | def test_new_keywords_start_with_empty_array 53 | prompt_id = 'new_keyword_test' 54 | 55 | # Create a prompt with a keyword that has no JSON history 56 | text = "Testing [NEW_KEYWORD] here." 57 | File.write(File.join(@temp_dir, "#{prompt_id}.txt"), text) 58 | 59 | prompt = PromptManager::Prompt.new(id: prompt_id) 60 | 61 | # New keywords should have empty array as value 62 | assert_equal [], prompt.parameters["[NEW_KEYWORD]"] 63 | end 64 | 65 | def test_keywords_with_existing_history_preserve_values 66 | prompt_id = 'history_test' 67 | 68 | # Create prompt and JSON with history 69 | text = "Hello [NAME]!" 70 | File.write(File.join(@temp_dir, "#{prompt_id}.txt"), text) 71 | 72 | params = { 73 | "[NAME]" => ["Alice", "Bob", "Charlie"] 74 | } 75 | File.write( 76 | File.join(@temp_dir, "#{prompt_id}.json"), 77 | JSON.pretty_generate(params) 78 | ) 79 | 80 | prompt = PromptManager::Prompt.new(id: prompt_id) 81 | 82 | # Should preserve the historical values 83 | assert_equal ["Alice", "Bob", "Charlie"], prompt.parameters["[NAME]"] 84 | end 85 | end -------------------------------------------------------------------------------- /examples/directives.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # encoding: utf-8 3 | # frozen_string_literal: true 4 | # warn_indent: true 5 | ########################################################## 6 | ### 7 | ## File: directives.rb 8 | ## Desc: Demo of the PromptManager and FileStorageAdapter 9 | ## By: Dewayne VanHoozer (dvanhoozer@gmail.com) 10 | ## 11 | # 12 | 13 | param1 = "param_one" 14 | param2 = "param_two" 15 | 16 | 17 | class MyDirectives 18 | def self.good_directive(*args) 19 | puts "inside #{__method__} with these parameters:" 20 | puts args.join(",\n") 21 | end 22 | end 23 | 24 | def concept_break = print "\n------------------------\n\n\n" 25 | 26 | require_relative '../lib/prompt_manager' 27 | require_relative '../lib/prompt_manager/storage/file_system_adapter' 28 | 29 | require 'amazing_print' 30 | require 'pathname' 31 | 32 | require 'debug_me' 33 | include DebugMe 34 | 35 | HERE = Pathname.new( __dir__ ) 36 | PROMPTS_DIR = HERE + "prompts_dir" 37 | 38 | 39 | ###################################################### 40 | # Main 41 | 42 | at_exit do 43 | puts 44 | puts "Done." 45 | puts 46 | end 47 | 48 | # Configure the Storage Adapter to use 49 | PromptManager::Storage::FileSystemAdapter.config do |config| 50 | config.prompts_dir = PROMPTS_DIR 51 | # config.search_proc = nil # default 52 | # config.prompt_extension = '.txt' # default 53 | # config.parms+_extension = '.json' # default 54 | end 55 | 56 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new 57 | 58 | # Use {parameter name} brackets to define a parameter 59 | # Note: must include capturing parentheses to make scan return arrays 60 | PromptManager::Prompt.parameter_regex = /(\{[A-Za-z _|]+\})/ 61 | 62 | # Retrieve a prompt 63 | # Note: The 'get' method returns a Hash, not a Prompt object 64 | # Use 'find' instead to get a Prompt object with methods 65 | prompt = PromptManager::Prompt.find(id: 'directive_example') 66 | 67 | # Shows prompt without comments or directives 68 | # It still has its parameter placeholders 69 | puts prompt 70 | concept_break 71 | 72 | puts "Directives are processed automatically when you call to_s on a prompt" 73 | puts "The DirectiveProcessor class handles directives like //include" 74 | puts "You don't need to process them manually" 75 | 76 | puts "Custom directive processing can be done by creating a custom DirectiveProcessor" 77 | puts "and setting it when creating a Prompt instance:" 78 | 79 | concept_break 80 | 81 | 82 | 83 | puts "Parameters in the prompt:" 84 | ap prompt.parameters 85 | puts "-"*16 86 | 87 | # Extract parameters from the prompt text using the parameter_regex 88 | puts "Parameters identified in the prompt text:" 89 | # With a capturing group, scan returns an array of arrays, so we need to flatten 90 | prompt_params = prompt.text.scan(PromptManager::Prompt.parameter_regex).flatten 91 | ap prompt_params 92 | concept_break 93 | 94 | # Set a parameter value (should be a string, not appending to an array) 95 | prompt.parameters['{language}'] = 'French' 96 | 97 | puts "After Substitution" 98 | puts prompt 99 | 100 | # Save the updated parameters 101 | prompt.save 102 | 103 | -------------------------------------------------------------------------------- /examples/prompts_dir/advanced_demo.txt: -------------------------------------------------------------------------------- 1 | # System Analysis and Historical Comparison Report 2 | # Generated with PromptManager - ERB + Shell Integration Demo 3 | 4 | ```markdown 5 | ## Current System Information 6 | 7 | **Timestamp**: <%= Time.now.strftime('%A, %B %d, %Y at %I:%M:%S %p %Z') %> 8 | **Analysis Duration**: <%= Time.now - Time.parse('2024-01-01') %> seconds since 2024 began 9 | 10 | ### Hardware Platform Details 11 | **Architecture**: $HOSTTYPE$MACHTYPE 12 | **Hostname**: $HOSTNAME 13 | **Operating System**: $OSTYPE 14 | **Shell**: $SHELL (version: $BASH_VERSION) 15 | **User**: $USER 16 | **Home Directory**: $HOME 17 | **Current Path**: $PWD 18 | **Terminal**: $TERM 19 | 20 | ### Detailed System Profile 21 | <% if RUBY_PLATFORM.include?('darwin') %> 22 | **Platform**: macOS/Darwin System 23 | **Ruby Platform**: <%= RUBY_PLATFORM %> 24 | **Ruby Version**: <%= RUBY_VERSION %> 25 | **Ruby Engine**: <%= RUBY_ENGINE %> 26 | <% elsif RUBY_PLATFORM.include?('linux') %> 27 | **Platform**: Linux System 28 | **Ruby Platform**: <%= RUBY_PLATFORM %> 29 | **Ruby Version**: <%= RUBY_VERSION %> 30 | **Ruby Engine**: <%= RUBY_ENGINE %> 31 | <% else %> 32 | **Platform**: Other Unix-like System 33 | **Ruby Platform**: <%= RUBY_PLATFORM %> 34 | **Ruby Version**: <%= RUBY_VERSION %> 35 | **Ruby Engine**: <%= RUBY_ENGINE %> 36 | <% end %> 37 | 38 | ### Environment Configuration 39 | **PATH**: $PATH 40 | **Language**: $LANG 41 | **Editor**: $EDITOR 42 | **Pager**: $PAGER 43 | 44 | ### Development Environment 45 | <% if ENV['RBENV_VERSION'] %> 46 | **Ruby Version Manager**: rbenv (version: <%= ENV['RBENV_VERSION'] %>) 47 | <% elsif ENV['RVM_VERSION'] %> 48 | **Ruby Version Manager**: RVM (version: <%= ENV['RVM_VERSION'] %>) 49 | <% else %> 50 | **Ruby Version Manager**: System Ruby or other 51 | <% end %> 52 | 53 | **Gem Home**: $GEM_HOME 54 | **Gem Path**: $GEM_PATH 55 | 56 | ### Performance Context 57 | **Load Average**: <%= `uptime`.strip rescue 'Unable to determine' %> 58 | **Memory Info**: <%= `vm_stat | head -5`.strip rescue 'Unable to determine' if RUBY_PLATFORM.include?('darwin') %> 59 | **Disk Usage**: <%= `df -h / | tail -1`.strip rescue 'Unable to determine' %> 60 | 61 | ## Analysis Request 62 | 63 | You are a technology historian and systems analyst. Please provide a comprehensive comparison between this current system and **the most powerful Apple computer created in the 20th century** (which would be from the 1990s). 64 | 65 | Consider these aspects in your analysis: 66 | 67 | 1. **Processing Power**: Compare the computational capabilities 68 | 2. **Memory and Storage**: Analyze RAM and storage differences 69 | 3. **Architecture Evolution**: Discuss the architectural changes 70 | 4. **Operating System**: Compare the OS sophistication 71 | 5. **Development Environment**: Contrast the programming environments 72 | 6. **Historical Context**: Put both systems in their historical perspective 73 | 7. **Price and Accessibility**: Consider cost and availability differences 74 | 8. **Legacy Impact**: How each system influenced computing 75 | 76 | Please be specific about which Apple computer from the 1990s you're comparing against, and provide concrete numbers where possible. Make the comparison engaging and educational, highlighting the dramatic evolution of computing power over the decades. 77 | 78 | **Format your response as a detailed technical report with clear sections and specific comparisons.** 79 | ``` 80 | -------------------------------------------------------------------------------- /examples/simple.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # encoding: utf-8 3 | # frozen_string_literal: true 4 | # warn_indent: true 5 | ########################################################## 6 | ### 7 | ## File: simple.rb 8 | ## Desc: Simple demo of the PromptManager and FileStorageAdapter 9 | ## By: Dewayne VanHoozer (dvanhoozer@gmail.com) 10 | ## 11 | # 12 | 13 | require 'prompt_manager' 14 | require 'prompt_manager/storage/file_system_adapter' 15 | 16 | require 'amazing_print' 17 | require 'pathname' 18 | 19 | HERE = Pathname.new( __dir__ ) 20 | PROMPTS_DIR = HERE + "prompts_dir" 21 | 22 | 23 | ###################################################### 24 | # Main 25 | 26 | at_exit do 27 | puts 28 | puts "Done." 29 | puts 30 | end 31 | 32 | # Configure the Storage Adapter to use 33 | PromptManager::Storage::FileSystemAdapter.config do |config| 34 | config.prompts_dir = PROMPTS_DIR 35 | # config.search_proc = nil # default 36 | # config.prompt_extension = '.txt' # default 37 | # config.parms+_extension = '.json' # default 38 | end 39 | 40 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new 41 | 42 | # Get a prompt 43 | # Note: The 'get' method returns a Hash, not a Prompt object 44 | # Use 'find' instead to get a Prompt object with methods 45 | 46 | todo = PromptManager::Prompt.find(id: 'todo') 47 | 48 | # This sequence simulates presenting each of the previously 49 | # used values for each keyword to the user to accept or 50 | # edit. 51 | 52 | # ap todo.keywords 53 | 54 | # This is a new keyword that was added after the current 55 | # todo.json file was created. Simulate the user setting 56 | # its value. 57 | 58 | todo.parameters["[KEYWORD_AKA_TODO]"] = "TODO" 59 | 60 | # When the parameter values change, the prompt must 61 | # be saved to persist the changes 62 | todo.save 63 | 64 | 65 | puts <<~EOS 66 | 67 | Raw Text from Prompt File 68 | includes all lines 69 | ========================= 70 | EOS 71 | 72 | puts todo.text 73 | 74 | 75 | puts <<~EOS 76 | 77 | Last Set of Parameters Used 78 | Includes those recently added 79 | ============================= 80 | EOS 81 | 82 | ap todo.parameters 83 | 84 | 85 | puts <<~EOS 86 | 87 | Prompt Ready to Send to gen-AI 88 | ============================== 89 | EOS 90 | 91 | puts todo.to_s 92 | 93 | puts <<~EOS 94 | 95 | When using the FileSystemAdapter for prompt storage you can have within 96 | the prompts_dir you can have many sub-directories. These sub-directories 97 | act like categories. The prompt ID is composed for the sub-directory name, 98 | a "/" character and then the normal prompt ID. For example "toy/8-ball" 99 | 100 | EOS 101 | 102 | magic = PromptManager::Prompt.find(id: 'toy/8-ball') 103 | 104 | puts "The magic PROMPT is:" 105 | puts magic 106 | puts 107 | puts "Remember if you want to see the full text of the prompt file:" 108 | puts magic.text 109 | 110 | puts "="*64 111 | 112 | puts <<~EOS 113 | 114 | The FileSystemAdapter also adds two new class methods to the Prompt class: 115 | 116 | list - provides an Array of prompt IDs 117 | path(prompt_id) - Returns a Pathname object to the prompt file 118 | 119 | EOS 120 | 121 | puts "List of prompts available" 122 | puts "=========================" 123 | 124 | puts PromptManager::Prompt.list 125 | 126 | puts <<~EOS 127 | 128 | And the path to the "toy/8-ball" prompt file is: 129 | 130 | #{PromptManager::Prompt.path('toy/8-ball')} 131 | 132 | Use "your_prompt.path" for when you want to do something with the 133 | the prompt file like send it to a text editor. 134 | 135 | Your can also use the class method if you supply a prompt_id 136 | like this: 137 | 138 | EOS 139 | 140 | puts PromptManager::Prompt.path('toy/8-ball') 141 | 142 | puts 143 | 144 | puts "Default Search for Prompts" 145 | puts "==========================" 146 | 147 | print "Search Proc Class: " 148 | puts PromptManager::Prompt.storage_adapter.search_proc.class 149 | 150 | search_term = "txt" # some comment lines show the file name example: todo.txt 151 | 152 | puts "Search for '#{search_term}' ..." 153 | 154 | prompt_ids = PromptManager::Prompt.search search_term 155 | 156 | # NOTE: prompt+ids is an Array of prompt IDs even if there is only one entry. 157 | # or and empty array if there are no prompts have the search term. 158 | 159 | puts "Found: #{prompt_ids}" 160 | 161 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | PATH 2 | remote: . 3 | specs: 4 | prompt_manager (0.5.8) 5 | 6 | GEM 7 | remote: https://rubygems.org/ 8 | specs: 9 | activemodel (8.0.2.1) 10 | activesupport (= 8.0.2.1) 11 | activerecord (8.0.2.1) 12 | activemodel (= 8.0.2.1) 13 | activesupport (= 8.0.2.1) 14 | timeout (>= 0.4.0) 15 | activesupport (8.0.2.1) 16 | base64 17 | benchmark (>= 0.3) 18 | bigdecimal 19 | concurrent-ruby (~> 1.0, >= 1.3.1) 20 | connection_pool (>= 2.2.5) 21 | drb 22 | i18n (>= 1.6, < 2) 23 | logger (>= 1.4.2) 24 | minitest (>= 5.1) 25 | securerandom (>= 0.3) 26 | tzinfo (~> 2.0, >= 2.0.5) 27 | uri (>= 0.13.1) 28 | amazing_print (1.8.1) 29 | base64 (0.3.0) 30 | benchmark (0.4.1) 31 | bigdecimal (3.2.2) 32 | cogger (1.5.0) 33 | core (~> 2.0) 34 | logger (~> 1.7) 35 | refinements (~> 13.5) 36 | tone (~> 2.0) 37 | zeitwerk (~> 2.7) 38 | concurrent-ruby (1.3.5) 39 | connection_pool (2.5.4) 40 | containable (1.3.0) 41 | concurrent-ruby (~> 1.3) 42 | core (2.3.0) 43 | debug_me (1.1.1) 44 | docile (1.4.1) 45 | drb (2.2.3) 46 | dry-configurable (1.3.0) 47 | dry-core (~> 1.1) 48 | zeitwerk (~> 2.6) 49 | dry-core (1.1.0) 50 | concurrent-ruby (~> 1.0) 51 | logger 52 | zeitwerk (~> 2.6) 53 | dry-inflector (1.2.0) 54 | dry-initializer (3.2.0) 55 | dry-logic (1.6.0) 56 | bigdecimal 57 | concurrent-ruby (~> 1.0) 58 | dry-core (~> 1.1) 59 | zeitwerk (~> 2.6) 60 | dry-monads (1.9.0) 61 | concurrent-ruby (~> 1.0) 62 | dry-core (~> 1.1) 63 | zeitwerk (~> 2.6) 64 | dry-schema (1.14.1) 65 | concurrent-ruby (~> 1.0) 66 | dry-configurable (~> 1.0, >= 1.0.1) 67 | dry-core (~> 1.1) 68 | dry-initializer (~> 3.2) 69 | dry-logic (~> 1.5) 70 | dry-types (~> 1.8) 71 | zeitwerk (~> 2.6) 72 | dry-types (1.8.3) 73 | bigdecimal (~> 3.0) 74 | concurrent-ruby (~> 1.0) 75 | dry-core (~> 1.0) 76 | dry-inflector (~> 1.0) 77 | dry-logic (~> 1.4) 78 | zeitwerk (~> 2.6) 79 | etcher (3.3.0) 80 | cogger (~> 1.0) 81 | core (~> 2.0) 82 | dry-monads (~> 1.9) 83 | dry-types (~> 1.7) 84 | refinements (~> 13.3) 85 | versionaire (~> 14.0) 86 | zeitwerk (~> 2.7) 87 | i18n (1.14.7) 88 | concurrent-ruby (~> 1.0) 89 | infusible (4.4.0) 90 | marameters (~> 4.1) 91 | logger (1.7.0) 92 | marameters (4.4.0) 93 | refinements (~> 13.3) 94 | zeitwerk (~> 2.7) 95 | mini_portile2 (2.8.9) 96 | minitest (5.25.5) 97 | optparse (0.6.0) 98 | ostruct (0.6.3) 99 | rake (13.3.0) 100 | refinements (13.5.0) 101 | runcom (12.3.0) 102 | refinements (~> 13.3) 103 | xdg (~> 9.0) 104 | zeitwerk (~> 2.7) 105 | securerandom (0.4.1) 106 | simplecov (0.22.0) 107 | docile (~> 1.1) 108 | simplecov-html (~> 0.11) 109 | simplecov_json_formatter (~> 0.1) 110 | simplecov-html (0.13.2) 111 | simplecov_json_formatter (0.1.4) 112 | sod (1.4.0) 113 | cogger (~> 1.0) 114 | containable (~> 1.1) 115 | infusible (~> 4.0) 116 | optparse (~> 0.6) 117 | refinements (~> 13.5) 118 | tone (~> 2.0) 119 | zeitwerk (~> 2.7) 120 | spek (4.4.0) 121 | core (~> 2.0) 122 | dry-monads (~> 1.9) 123 | refinements (~> 13.3) 124 | versionaire (~> 14.0) 125 | zeitwerk (~> 2.7) 126 | sqlite3 (2.7.3) 127 | mini_portile2 (~> 2.8.0) 128 | sqlite3 (2.7.3-arm64-darwin) 129 | timeout (0.4.3) 130 | tocer (19.3.0) 131 | cogger (~> 1.0) 132 | containable (~> 1.1) 133 | core (~> 2.0) 134 | dry-schema (~> 1.13) 135 | etcher (~> 3.0) 136 | infusible (~> 4.0) 137 | refinements (~> 13.3) 138 | runcom (~> 12.0) 139 | sod (~> 1.0) 140 | spek (~> 4.0) 141 | zeitwerk (~> 2.7) 142 | tone (2.4.0) 143 | refinements (~> 13.3) 144 | zeitwerk (~> 2.7) 145 | tzinfo (2.0.6) 146 | concurrent-ruby (~> 1.0) 147 | uri (1.0.3) 148 | versionaire (14.3.0) 149 | refinements (~> 13.3) 150 | xdg (9.3.0) 151 | zeitwerk (2.7.3) 152 | 153 | PLATFORMS 154 | arm64-darwin-23 155 | ruby 156 | 157 | DEPENDENCIES 158 | activerecord 159 | amazing_print 160 | debug_me 161 | minitest 162 | ostruct 163 | prompt_manager! 164 | rake 165 | simplecov 166 | sqlite3 167 | tocer 168 | 169 | BUNDLED WITH 170 | 2.7.1 171 | -------------------------------------------------------------------------------- /docs/storage/custom-adapters.md: -------------------------------------------------------------------------------- 1 | # Custom Storage Adapters 2 | 3 | Create custom storage adapters to integrate PromptManager with any storage system. 4 | 5 | ## Adapter Interface 6 | 7 | All storage adapters must inherit from `PromptManager::Storage::Base` and implement the required methods: 8 | 9 | ```ruby 10 | class CustomAdapter < PromptManager::Storage::Base 11 | def initialize(**options) 12 | # Initialize your storage connection 13 | super 14 | end 15 | 16 | def read(prompt_id) 17 | # Return the prompt content as a string 18 | # Raise PromptManager::PromptNotFoundError if not found 19 | end 20 | 21 | def write(prompt_id, content) 22 | # Save the prompt content 23 | # Return true on success 24 | end 25 | 26 | def exist?(prompt_id) 27 | # Return true if prompt exists 28 | end 29 | 30 | def delete(prompt_id) 31 | # Remove the prompt 32 | # Return true on success 33 | end 34 | 35 | def list 36 | # Return array of all prompt IDs 37 | end 38 | end 39 | ``` 40 | 41 | ## Example: Redis Adapter 42 | 43 | ```ruby 44 | require 'redis' 45 | 46 | class RedisAdapter < PromptManager::Storage::Base 47 | def initialize(redis_url: 'redis://localhost:6379', key_prefix: 'prompts:', **options) 48 | @redis = Redis.new(url: redis_url) 49 | @key_prefix = key_prefix 50 | super(**options) 51 | end 52 | 53 | def read(prompt_id) 54 | content = @redis.get(redis_key(prompt_id)) 55 | raise PromptManager::PromptNotFoundError.new("Prompt '#{prompt_id}' not found") unless content 56 | content 57 | end 58 | 59 | def write(prompt_id, content) 60 | @redis.set(redis_key(prompt_id), content) 61 | true 62 | end 63 | 64 | def exist?(prompt_id) 65 | @redis.exists?(redis_key(prompt_id)) > 0 66 | end 67 | 68 | def delete(prompt_id) 69 | @redis.del(redis_key(prompt_id)) > 0 70 | end 71 | 72 | def list 73 | keys = @redis.keys("#{@key_prefix}*") 74 | keys.map { |key| key.sub(@key_prefix, '') } 75 | end 76 | 77 | private 78 | 79 | def redis_key(prompt_id) 80 | "#{@key_prefix}#{prompt_id}" 81 | end 82 | end 83 | 84 | # Configure PromptManager to use Redis 85 | PromptManager.configure do |config| 86 | config.storage = RedisAdapter.new( 87 | redis_url: ENV['REDIS_URL'], 88 | key_prefix: 'myapp:prompts:' 89 | ) 90 | end 91 | ``` 92 | 93 | ## Example: S3 Adapter 94 | 95 | ```ruby 96 | require 'aws-sdk-s3' 97 | 98 | class S3Adapter < PromptManager::Storage::Base 99 | def initialize(bucket:, region: 'us-east-1', key_prefix: 'prompts/', **options) 100 | @bucket = bucket 101 | @key_prefix = key_prefix 102 | @s3 = Aws::S3::Client.new(region: region) 103 | super(**options) 104 | end 105 | 106 | def read(prompt_id) 107 | response = @s3.get_object( 108 | bucket: @bucket, 109 | key: s3_key(prompt_id) 110 | ) 111 | response.body.read 112 | rescue Aws::S3::Errors::NoSuchKey 113 | raise PromptManager::PromptNotFoundError.new("Prompt '#{prompt_id}' not found") 114 | end 115 | 116 | def write(prompt_id, content) 117 | @s3.put_object( 118 | bucket: @bucket, 119 | key: s3_key(prompt_id), 120 | body: content, 121 | content_type: 'text/plain' 122 | ) 123 | true 124 | end 125 | 126 | def exist?(prompt_id) 127 | @s3.head_object(bucket: @bucket, key: s3_key(prompt_id)) 128 | true 129 | rescue Aws::S3::Errors::NotFound 130 | false 131 | end 132 | 133 | def delete(prompt_id) 134 | @s3.delete_object(bucket: @bucket, key: s3_key(prompt_id)) 135 | true 136 | end 137 | 138 | def list 139 | response = @s3.list_objects_v2( 140 | bucket: @bucket, 141 | prefix: @key_prefix 142 | ) 143 | 144 | response.contents.map do |object| 145 | object.key.sub(@key_prefix, '') 146 | end 147 | end 148 | 149 | private 150 | 151 | def s3_key(prompt_id) 152 | "#{@key_prefix}#{prompt_id}.txt" 153 | end 154 | end 155 | ``` 156 | 157 | ## Best Practices 158 | 159 | 1. **Error Handling**: Always raise appropriate exceptions 160 | 2. **Connection Management**: Handle connection failures gracefully 161 | 3. **Performance**: Implement connection pooling where appropriate 162 | 4. **Security**: Use proper authentication and encryption 163 | 5. **Testing**: Write comprehensive tests for your adapter 164 | 6. **Documentation**: Document configuration options and requirements 165 | 166 | ## Configuration 167 | 168 | Register your custom adapter: 169 | 170 | ```ruby 171 | PromptManager.configure do |config| 172 | config.storage = CustomAdapter.new( 173 | # Your adapter configuration 174 | ) 175 | end 176 | ``` -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: PromptManager Documentation 2 | site_description: Comprehensive documentation for the PromptManager Ruby gem - Manage parameterized prompts for generative AI 3 | site_author: MadBomber 4 | site_url: https://madbomber.github.io/prompt_manager 5 | repo_url: https://github.com/MadBomber/prompt_manager 6 | repo_name: MadBomber/prompt_manager 7 | edit_uri: edit/main/docs/ 8 | 9 | theme: 10 | name: material 11 | logo: assets/logo.svg 12 | favicon: assets/favicon.ico 13 | palette: 14 | - media: "(prefers-color-scheme: light)" 15 | scheme: default 16 | primary: indigo 17 | accent: amber 18 | toggle: 19 | icon: material/brightness-7 20 | name: Switch to dark mode 21 | - media: "(prefers-color-scheme: dark)" 22 | scheme: slate 23 | primary: indigo 24 | accent: amber 25 | toggle: 26 | icon: material/brightness-4 27 | name: Switch to light mode 28 | features: 29 | - navigation.instant 30 | - navigation.tracking 31 | - navigation.tabs 32 | - navigation.tabs.sticky 33 | - navigation.sections 34 | - navigation.expand 35 | - navigation.path 36 | - navigation.prune 37 | - navigation.indexes 38 | - navigation.top 39 | - toc.follow 40 | - toc.integrate 41 | - search.suggest 42 | - search.highlight 43 | - search.share 44 | - header.autohide 45 | - content.code.copy 46 | - content.code.annotate 47 | - content.tabs.link 48 | 49 | plugins: 50 | - search: 51 | separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' 52 | 53 | markdown_extensions: 54 | - abbr 55 | - admonition 56 | - attr_list 57 | - def_list 58 | - footnotes 59 | - md_in_html 60 | - toc: 61 | permalink: true 62 | toc_depth: 3 63 | - pymdownx.arithmatex: 64 | generic: true 65 | - pymdownx.betterem: 66 | smart_enable: all 67 | - pymdownx.caret 68 | - pymdownx.details 69 | - pymdownx.emoji: 70 | emoji_index: !!python/name:material.extensions.emoji.twemoji 71 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 72 | - pymdownx.highlight: 73 | anchor_linenums: true 74 | line_spans: __span 75 | pygments_lang_class: true 76 | - pymdownx.inlinehilite 77 | - pymdownx.keys 78 | - pymdownx.mark 79 | - pymdownx.smartsymbols 80 | - pymdownx.superfences: 81 | custom_fences: 82 | - name: mermaid 83 | class: mermaid 84 | format: !!python/name:pymdownx.superfences.fence_code_format 85 | - pymdownx.tabbed: 86 | alternate_style: true 87 | - pymdownx.tasklist: 88 | custom_checkbox: true 89 | - pymdownx.tilde 90 | 91 | extra: 92 | social: 93 | - icon: fontawesome/brands/github 94 | link: https://github.com/MadBomber/prompt_manager 95 | name: GitHub Repository 96 | - icon: fontawesome/solid/gem 97 | link: https://rubygems.org/gems/prompt_manager 98 | name: RubyGems Package 99 | version: 100 | provider: mike 101 | default: latest 102 | 103 | nav: 104 | - Home: index.md 105 | - Getting Started: 106 | - Installation: getting-started/installation.md 107 | - Quick Start: getting-started/quick-start.md 108 | - Basic Concepts: getting-started/basic-concepts.md 109 | - Core Features: 110 | - Parameterized Prompts: core-features/parameterized-prompts.md 111 | - Directive Processing: core-features/directive-processing.md 112 | - ERB Integration: core-features/erb-integration.md 113 | - Shell Integration: core-features/shell-integration.md 114 | - Comments & Documentation: core-features/comments.md 115 | - Parameter History: core-features/parameter-history.md 116 | - Error Handling: core-features/error-handling.md 117 | - Storage Adapters: 118 | - Overview: storage/overview.md 119 | - FileSystemAdapter: storage/filesystem-adapter.md 120 | - ActiveRecordAdapter: storage/activerecord-adapter.md 121 | - Custom Adapters: storage/custom-adapters.md 122 | - API Reference: 123 | - Prompt Class: api/prompt-class.md 124 | - Storage Adapters: api/storage-adapters.md 125 | - Directive Processor: api/directive-processor.md 126 | - Configuration: api/configuration.md 127 | - Advanced Usage: 128 | - Custom Keywords: advanced/custom-keywords.md 129 | - Dynamic Directives: advanced/dynamic-directives.md 130 | - Search Integration: advanced/search-integration.md 131 | - Performance Tips: advanced/performance.md 132 | - Examples: 133 | - Overview: examples.md 134 | - Basic Examples: examples/basic.md 135 | - Advanced Examples: examples/advanced.md 136 | - Real World Use Cases: examples/real-world.md 137 | - Development: 138 | - Architecture: development/architecture.md 139 | - Contributing: development/contributing.md 140 | - Testing: development/testing.md 141 | - Roadmap: development/roadmap.md 142 | - Migration Guides: 143 | - Version 0.9.0: migration/v0.9.0.md 144 | - Version 1.0.0: migration/v1.0.0.md 145 | 146 | copyright: Copyright © 2024 MadBomber - MIT License -------------------------------------------------------------------------------- /docs/core-features/error-handling.md: -------------------------------------------------------------------------------- 1 | # Error Handling 2 | 3 | PromptManager provides comprehensive error handling to help you identify and resolve issues during prompt processing. 4 | 5 | ## Common Exceptions 6 | 7 | ### `PromptNotFoundError` 8 | 9 | Raised when a prompt cannot be located: 10 | 11 | ```ruby 12 | begin 13 | prompt = PromptManager::Prompt.new(id: 'nonexistent_prompt') 14 | rescue PromptManager::PromptNotFoundError => e 15 | puts "Prompt not found: #{e.message}" 16 | # Handle gracefully - perhaps show available prompts 17 | end 18 | ``` 19 | 20 | ### `MissingParametersError` 21 | 22 | Raised when required parameters are not provided: 23 | 24 | ```ruby 25 | begin 26 | result = prompt.render # Missing required parameters 27 | rescue PromptManager::MissingParametersError => e 28 | puts "Missing parameters: #{e.missing_parameters.join(', ')}" 29 | # Prompt user for missing values 30 | end 31 | ``` 32 | 33 | ### `DirectiveProcessingError` 34 | 35 | Raised when directive processing fails: 36 | 37 | ```ruby 38 | begin 39 | result = prompt.render 40 | rescue PromptManager::DirectiveProcessingError => e 41 | puts "Directive error: #{e.message}" 42 | puts "Line: #{e.line_number}" if e.respond_to?(:line_number) 43 | end 44 | ``` 45 | 46 | ### `StorageError` 47 | 48 | Raised when storage operations fail: 49 | 50 | ```ruby 51 | begin 52 | prompt = PromptManager::Prompt.new(id: 'my_prompt') 53 | rescue PromptManager::StorageError => e 54 | puts "Storage error: #{e.message}" 55 | # Check file permissions, disk space, etc. 56 | end 57 | ``` 58 | 59 | ## Error Recovery Strategies 60 | 61 | ### Graceful Degradation 62 | 63 | ```ruby 64 | def safe_render_prompt(prompt_id, params = {}) 65 | begin 66 | prompt = PromptManager::Prompt.new(id: prompt_id) 67 | prompt.render(params) 68 | rescue PromptManager::PromptNotFoundError 69 | "Default response when prompt is unavailable" 70 | rescue PromptManager::MissingParametersError => e 71 | "Please provide: #{e.missing_parameters.join(', ')}" 72 | rescue => e 73 | logger.error "Unexpected error rendering prompt: #{e.message}" 74 | "An error occurred processing your request" 75 | end 76 | end 77 | ``` 78 | 79 | ### Retry Logic 80 | 81 | ```ruby 82 | def render_with_retry(prompt, params, max_retries: 3) 83 | retries = 0 84 | 85 | begin 86 | prompt.render(params) 87 | rescue PromptManager::StorageError => e 88 | retries += 1 89 | if retries <= max_retries 90 | sleep(0.5 * retries) # Exponential backoff 91 | retry 92 | else 93 | raise e 94 | end 95 | end 96 | end 97 | ``` 98 | 99 | ## Validation and Prevention 100 | 101 | ### Parameter Validation 102 | 103 | ```ruby 104 | def validate_parameters(params, required_params) 105 | missing = required_params - params.keys 106 | 107 | unless missing.empty? 108 | raise PromptManager::MissingParametersError.new( 109 | "Missing required parameters: #{missing.join(', ')}", 110 | missing_parameters: missing 111 | ) 112 | end 113 | end 114 | 115 | # Usage 116 | validate_parameters(user_params, [:customer_name, :order_id]) 117 | ``` 118 | 119 | ### Pre-flight Checks 120 | 121 | ```ruby 122 | def preflight_check(prompt_id) 123 | # Check if prompt exists 124 | unless PromptManager.storage.exist?(prompt_id) 125 | raise PromptManager::PromptNotFoundError, "Prompt '#{prompt_id}' not found" 126 | end 127 | 128 | # Check for circular includes 129 | check_circular_includes(prompt_id) 130 | 131 | # Validate syntax 132 | validate_prompt_syntax(prompt_id) 133 | end 134 | ``` 135 | 136 | ## Logging and Debugging 137 | 138 | ### Enable Debug Logging 139 | 140 | ```ruby 141 | PromptManager.configure do |config| 142 | config.debug = true 143 | config.logger = Logger.new(STDOUT) 144 | end 145 | ``` 146 | 147 | ### Custom Error Handlers 148 | 149 | ```ruby 150 | PromptManager.configure do |config| 151 | config.error_handler = ->(error, context) { 152 | # Custom error handling 153 | ErrorReporter.notify(error, context: context) 154 | 155 | # Return fallback response 156 | case error 157 | when PromptManager::PromptNotFoundError 158 | "Prompt temporarily unavailable" 159 | when PromptManager::MissingParametersError 160 | "Please check your input parameters" 161 | else 162 | "Service temporarily unavailable" 163 | end 164 | } 165 | end 166 | ``` 167 | 168 | ## Testing Error Conditions 169 | 170 | ### RSpec Examples 171 | 172 | ```ruby 173 | describe "Error handling" do 174 | it "handles missing prompts gracefully" do 175 | expect { 176 | PromptManager::Prompt.new(id: 'nonexistent') 177 | }.to raise_error(PromptManager::PromptNotFoundError) 178 | end 179 | 180 | it "validates required parameters" do 181 | prompt = PromptManager::Prompt.new(id: 'test_prompt') 182 | 183 | expect { 184 | prompt.render # No parameters provided 185 | }.to raise_error(PromptManager::MissingParametersError) 186 | end 187 | end 188 | ``` 189 | 190 | ## Best Practices 191 | 192 | 1. **Always Handle Exceptions**: Never let PromptManager exceptions bubble up unhandled 193 | 2. **Provide Meaningful Fallbacks**: Return sensible defaults when prompts fail 194 | 3. **Log Errors**: Capture error details for debugging and monitoring 195 | 4. **Validate Early**: Check parameters and conditions before processing 196 | 5. **Test Error Paths**: Include error scenarios in your test suite 197 | 6. **Monitor in Production**: Set up alerts for prompt processing failures -------------------------------------------------------------------------------- /test/prompt_manager/storage/active_record_adapter_test.rb: -------------------------------------------------------------------------------- 1 | # test/test_prompt_manager_storage_active_record_adapter.rb 2 | 3 | require 'test_helper' 4 | 5 | require 'active_record' 6 | require 'json' 7 | 8 | 9 | require 'prompt_manager/storage/active_record_adapter' 10 | 11 | ############################################################ 12 | ### 13 | ## Setup the database from the application's point of view 14 | # 15 | 16 | ActiveRecord::Base 17 | .establish_connection( 18 | adapter: 'sqlite3', 19 | database: ':memory:' 20 | ) 21 | 22 | ActiveRecord::Schema.define do 23 | create_table :db_prompts do |t| 24 | t.string :prompt_name 25 | t.string :prompt_text 26 | t.text :prompt_params 27 | end 28 | end 29 | 30 | 31 | # Within a Rails application this could be ApplicationRecord 32 | class DbPrompt < ActiveRecord::Base 33 | serialize :prompt_params 34 | end 35 | 36 | # 37 | ## database setyo frin aookucatuib's POV 38 | ### 39 | ############################################################ 40 | 41 | 42 | class TestActiveRecordAdapter < Minitest::Test 43 | def setup 44 | # The @storage_adapter object used by the PromptManager::Prompt class 45 | # is an instance of the storage adapter class. 46 | @adapter = PromptManager::Storage::ActiveRecordAdapter.config do |config| 47 | config.model = DbPrompt 48 | config.id_column = :prompt_name 49 | config.text_column = :prompt_text 50 | config.parameters_column = :prompt_params 51 | end.new 52 | end 53 | 54 | 55 | ################################################# 56 | 57 | def test_config 58 | assert_equal DbPrompt, @adapter.model 59 | assert_equal :prompt_name, @adapter.id_column 60 | assert_equal :prompt_text, @adapter.text_column 61 | assert_equal :prompt_params, @adapter.parameters_column 62 | end 63 | 64 | 65 | def test_save 66 | @adapter.save(id: 'example_name', text: 'Example prompt', parameters: { size: 'large' }) 67 | 68 | prompt_record = DbPrompt.find_by(prompt_name: 'example_name') 69 | 70 | assert prompt_record 71 | assert_equal 'Example prompt', prompt_record.prompt_text 72 | assert_equal({size: 'large'}, prompt_record.prompt_params) # Updated expectation to match ActiveRecord's behavior 73 | end 74 | 75 | 76 | def test_get 77 | prompt_id = "example_name_#{rand(10000)}" 78 | 79 | DbPrompt.destroy(id: prompt_id) rescue 80 | 81 | DbPrompt.create( 82 | prompt_name: prompt_id, 83 | prompt_text: 'Updated prompt', 84 | prompt_params: { size: 'large' }.to_json 85 | ) 86 | 87 | # The result is a Hash having the three keys expected 88 | # by the PromptManager::Prompt class 89 | result = @adapter.get(id: prompt_id) 90 | 91 | expected_parameters = { size: 'large' } 92 | 93 | assert_equal Hash, result.class 94 | assert_equal prompt_id, result[:id] 95 | assert_equal 'Updated prompt', result[:text] 96 | assert_equal expected_parameters, result[:parameters].symbolize_keys 97 | end 98 | 99 | 100 | def test_list 101 | DbPrompt.create(prompt_name: 'example_name_1', prompt_text: 'Example prompt 1') 102 | DbPrompt.create(prompt_name: 'example_name_2', prompt_text: 'Example prompt 2') 103 | 104 | ids = @adapter.list 105 | assert_includes ids, 'example_name_1' 106 | assert_includes ids, 'example_name_2' 107 | end 108 | 109 | 110 | def test_delete 111 | DbPrompt.find_or_initialize_by( 112 | prompt_name: 'delete_me', 113 | prompt_text: 'Example prompt to be deleted' 114 | ).save 115 | 116 | assert @adapter.get(id: 'delete_me') 117 | 118 | @adapter.delete(id: 'delete_me') 119 | 120 | assert_raises ArgumentError do 121 | @adapter.get(id: 'delete_me') 122 | end 123 | end 124 | 125 | 126 | def test_save_with_existing_record 127 | @adapter.save(id: 'example_name', text: 'Updated prompt', parameters: { size: 'small' }) 128 | prompt_record = DbPrompt.find_by(prompt_name: 'example_name') 129 | assert_equal 'Updated prompt', prompt_record.prompt_text 130 | assert_equal({ size: 'small' }, prompt_record.prompt_params) 131 | end 132 | 133 | 134 | def test_create 135 | DbPrompt.create(prompt_name: 'example_name_1', prompt_text: 'Example prompt 1') 136 | DbPrompt.create(prompt_name: 'example_name_2', prompt_text: 'Another example 2') 137 | 138 | search_result = @adapter.search('Another') 139 | assert_includes search_result, 'example_name_2' 140 | refute_includes search_result, 'example_name_1' 141 | end 142 | 143 | # Add tests to cover missing method behavior and validation of configuration. 144 | 145 | # Add test for method_missing 146 | def test_method_missing_delegates_to_record 147 | # DbPrompt.create(prompt_name: 'example_name', prompt_text: 'Example prompt') 148 | # @adapter.get(id: 'example_name') 149 | 150 | assert_respond_to @adapter, :where # Assuming `where` is the method missing 151 | # assert_equal 'Example prompt', @adapter.prompt_text 152 | end 153 | 154 | 155 | def test_respond_to_missing_handles_record_methods 156 | assert_respond_to @adapter, :find_by_prompt_name # Assuming record will have a `find_by_prompt_name` method 157 | end 158 | 159 | 160 | def test_validate_configuration 161 | assert_raises(ArgumentError) do 162 | PromptManager::Storage::ActiveRecordAdapter.config do |config| 163 | config.model = nil 164 | end 165 | end 166 | end 167 | end 168 | 169 | -------------------------------------------------------------------------------- /lib/prompt_manager/storage/active_record_adapter.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/lib/prompt_manager/storage/active_record_adapter.rb 2 | 3 | # This class acts as an adapter for interacting with an ActiveRecord model 4 | require 'active_record' 5 | # to manage storage operations for PromptManager::Prompt instances. It defines 6 | # methods that allow for saving, searching, retrieving by ID, and deleting 7 | # prompts. 8 | # 9 | # To use this adapter, you must configure it with an ActiveRecord model and 10 | # the column names for ID, text content, and parameters. The adapter will 11 | # handle serialization and deserialization of parameters. 12 | # 13 | # This adapter is used by PromptManager::Prompt as its storage backend, enabling CRUD operations on persistent prompt data. 14 | 15 | class PromptManager::Storage::ActiveRecordAdapter 16 | 17 | class << self 18 | # Configure the ActiveRecord model and column mappings 19 | attr_accessor :model, 20 | :id_column, 21 | :text_column, 22 | :parameters_column 23 | 24 | # Configure the adapter with the required settings 25 | # Must be called with a block before using the adapter 26 | def config 27 | if block_given? 28 | yield self 29 | validate_configuration 30 | else 31 | raise ArgumentError, "No block given to config" 32 | end 33 | 34 | self 35 | end 36 | 37 | # Validate that all required configuration is present and valid 38 | def validate_configuration 39 | validate_model 40 | validate_columns 41 | end 42 | 43 | # Ensure the provided model is a valid ActiveRecord model 44 | def validate_model 45 | raise ArgumentError, "AR Model not set" unless model 46 | raise ArgumentError, "AR Model is not an ActiveRecord model" unless model < ActiveRecord::Base 47 | end 48 | 49 | # Verify that all required columns exist in the model 50 | def validate_columns 51 | columns = model.column_names # Array of Strings 52 | [id_column, text_column, parameters_column].each do |column| 53 | raise ArgumentError, "#{column} is not a valid column for model #{model}" unless columns.include?(column.to_s) 54 | end 55 | end 56 | 57 | # Delegate unknown methods to the ActiveRecord model 58 | def method_missing(method_name, *args, &block) 59 | if model.respond_to?(method_name) 60 | model.send(method_name, *args, &block) 61 | else 62 | super 63 | end 64 | end 65 | 66 | # Support respond_to? for delegated methods 67 | def respond_to_missing?(method_name, include_private = false) 68 | model.respond_to?(method_name, include_private) || super 69 | end 70 | end 71 | 72 | 73 | ############################################## 74 | # The ActiveRecord object representing the current prompt 75 | attr_accessor :record 76 | 77 | # Accessor methods to avoid repeated self.class prefixes 78 | def model = self.class.model 79 | def id_column = self.class.id_column 80 | def text_column = self.class.text_column 81 | def parameters_column = self.class.parameters_column 82 | 83 | # Initialize the adapter and validate configuration 84 | def initialize 85 | self.class.send(:validate_configuration) # send gets around private designations of a method 86 | @record = model.first 87 | end 88 | 89 | # Retrieve a prompt by its ID 90 | # Returns a hash with id, text, and parameters 91 | def get(id:) 92 | @record = model.find_by(id_column => id) 93 | raise ArgumentError, "Prompt not found with id: #{id}" unless @record 94 | 95 | # Handle case where parameters might be stored as a JSON string 96 | # instead of a native Hash 97 | parameters = @record[parameters_column] 98 | 99 | if parameters.is_a? String 100 | parameters = JSON.parse parameters 101 | end 102 | 103 | { 104 | id: id, 105 | text: @record[text_column], 106 | parameters: parameters 107 | } 108 | end 109 | 110 | # Save a prompt with the given ID, text, and parameters 111 | # Creates a new record if one doesn't exist, otherwise updates existing record 112 | def save(id:, text: "", parameters: {}) 113 | @record = model.find_or_initialize_by(id_column => id) 114 | 115 | @record[text_column] = text 116 | @record[parameters_column] = parameters 117 | @record.save! 118 | end 119 | 120 | # Delete a prompt with the given ID 121 | def delete(id:) 122 | @record = model.find_by(id_column => id) 123 | @record&.destroy 124 | end 125 | 126 | # Return an array of all prompt IDs 127 | def list(*) 128 | model.all.pluck(id_column) 129 | end 130 | 131 | # Search for prompts containing the given text 132 | # Returns an array of matching prompt IDs 133 | def search(for_what) 134 | model.where("#{text_column} LIKE ?", "%#{for_what}%").pluck(id_column) 135 | end 136 | 137 | ############################################## 138 | private 139 | 140 | # Delegate unknown methods to the current record 141 | def method_missing(method_name, *args, &block) 142 | if @record && @record.respond_to?(method_name) 143 | @record.send(method_name, *args, &block) 144 | elsif model.respond_to?(method_name) 145 | model.send(method_name, *args, &block) 146 | else 147 | super 148 | end 149 | end 150 | 151 | # Support respond_to? for delegated methods 152 | def respond_to_missing?(method_name, include_private = false) 153 | (model.respond_to?(method_name, include_private) || 154 | (@record && @record.respond_to?(method_name, include_private)) || 155 | super) 156 | end 157 | end 158 | -------------------------------------------------------------------------------- /docs/storage/filesystem-adapter.md: -------------------------------------------------------------------------------- 1 | # FileSystemAdapter 2 | 3 | The FileSystemAdapter is the default storage adapter for PromptManager, storing prompts as files in a directory structure. 4 | 5 | ## Overview 6 | 7 | The FileSystemAdapter stores prompts as individual text files in a configurable directory. This is the simplest and most common storage method. 8 | 9 | ## Configuration 10 | 11 | ### Basic Setup 12 | 13 | ```ruby 14 | require 'prompt_manager' 15 | 16 | # Use default filesystem storage (~/prompts_dir/) 17 | prompt = PromptManager::Prompt.new(id: 'welcome_message') 18 | ``` 19 | 20 | ### Custom Directory 21 | 22 | ```ruby 23 | PromptManager.configure do |config| 24 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 25 | prompts_dir: '/path/to/your/prompts' 26 | ) 27 | end 28 | ``` 29 | 30 | ### Multiple Directories 31 | 32 | ```ruby 33 | # Search multiple directories in order 34 | PromptManager.configure do |config| 35 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 36 | prompts_dir: [ 37 | '/home/user/project_prompts', 38 | '/shared/common_prompts', 39 | '/system/default_prompts' 40 | ] 41 | ) 42 | end 43 | ``` 44 | 45 | ## Directory Structure 46 | 47 | ### Basic Structure 48 | 49 | ``` 50 | prompts_dir/ 51 | ├── welcome_message.txt 52 | ├── error_response.txt 53 | ├── customer_service/ 54 | │ ├── greeting.txt 55 | │ └── farewell.txt 56 | └── templates/ 57 | ├── email_header.txt 58 | └── email_footer.txt 59 | ``` 60 | 61 | ### Organizing Prompts 62 | 63 | ```ruby 64 | # Access nested prompts using path separators 65 | customer_greeting = PromptManager::Prompt.new(id: 'customer_service/greeting') 66 | email_header = PromptManager::Prompt.new(id: 'templates/email_header') 67 | ``` 68 | 69 | ## File Operations 70 | 71 | ### Creating Prompts 72 | 73 | ```ruby 74 | # Prompts are created as .txt files 75 | prompt = PromptManager::Prompt.new(id: 'new_prompt') 76 | prompt.save("Your prompt content here...") 77 | # Creates: prompts_dir/new_prompt.txt 78 | ``` 79 | 80 | ### Reading Prompts 81 | 82 | ```ruby 83 | # Automatically reads from filesystem 84 | prompt = PromptManager::Prompt.new(id: 'existing_prompt') 85 | content = prompt.render 86 | ``` 87 | 88 | ### Updating Prompts 89 | 90 | ```ruby 91 | # Modify the file directly or use save method 92 | prompt = PromptManager::Prompt.new(id: 'existing_prompt') 93 | prompt.save("Updated content...") 94 | ``` 95 | 96 | ### Deleting Prompts 97 | 98 | ```ruby 99 | # Remove the prompt file 100 | prompt = PromptManager::Prompt.new(id: 'old_prompt') 101 | prompt.delete 102 | ``` 103 | 104 | ## Advanced Features 105 | 106 | ### File Extensions 107 | 108 | The adapter supports different file extensions: 109 | 110 | ```ruby 111 | # These all work: 112 | # - welcome.txt 113 | # - welcome.md 114 | # - welcome.prompt 115 | # - welcome (no extension) 116 | 117 | prompt = PromptManager::Prompt.new(id: 'welcome') 118 | # Searches for welcome.txt, then welcome.md, etc. 119 | ``` 120 | 121 | ### Directory Search Order 122 | 123 | When using multiple directories, the adapter searches in order: 124 | 125 | ```ruby 126 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 127 | prompts_dir: [ 128 | './project_prompts', # First priority 129 | '~/shared_prompts', # Second priority 130 | '/system/prompts' # Last resort 131 | ] 132 | ) 133 | ``` 134 | 135 | ### Permissions and Security 136 | 137 | ```ruby 138 | # Set directory permissions 139 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 140 | prompts_dir: '/secure/prompts', 141 | file_mode: 0600, # Read/write for owner only 142 | dir_mode: 0700 # Access for owner only 143 | ) 144 | ``` 145 | 146 | ## Error Handling 147 | 148 | ### Common Issues 149 | 150 | ```ruby 151 | begin 152 | prompt = PromptManager::Prompt.new(id: 'missing_prompt') 153 | rescue PromptManager::PromptNotFoundError => e 154 | puts "Prompt file not found: #{e.message}" 155 | end 156 | 157 | begin 158 | prompt.save("content") 159 | rescue PromptManager::StorageError => e 160 | puts "Cannot write file: #{e.message}" 161 | # Check permissions, disk space, etc. 162 | end 163 | ``` 164 | 165 | ### File System Monitoring 166 | 167 | ```ruby 168 | # Watch for file changes (requires additional gems) 169 | require 'listen' 170 | 171 | listener = Listen.to('/path/to/prompts') do |modified, added, removed| 172 | puts "Prompts changed: #{modified + added + removed}" 173 | # Reload prompts if needed 174 | end 175 | 176 | listener.start 177 | ``` 178 | 179 | ## Performance Considerations 180 | 181 | ### Caching 182 | 183 | ```ruby 184 | # Enable file content caching 185 | PromptManager.configure do |config| 186 | config.cache_prompts = true 187 | config.cache_ttl = 300 # 5 minutes 188 | end 189 | ``` 190 | 191 | ### Large Directories 192 | 193 | For directories with many prompts: 194 | 195 | ```ruby 196 | # Use indexing for faster lookups 197 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 198 | prompts_dir: '/large/prompt/directory', 199 | enable_indexing: true, 200 | index_file: '.prompt_index' 201 | ) 202 | ``` 203 | 204 | ## Best Practices 205 | 206 | 1. **Organize by Purpose**: Use subdirectories to group related prompts 207 | 2. **Consistent Naming**: Use clear, descriptive prompt IDs 208 | 3. **Version Control**: Store your prompts directory in git 209 | 4. **Backup Strategy**: Regular backups of your prompts directory 210 | 5. **File Permissions**: Secure sensitive prompts with appropriate permissions 211 | 6. **Documentation**: Use comments in prompt files to document purpose and usage 212 | 213 | ## Migration from Other Storage 214 | 215 | ### From Database 216 | 217 | ```ruby 218 | # Export database prompts to filesystem 219 | database_adapter.all_prompts.each do |prompt_id, content| 220 | file_path = File.join(prompts_dir, "#{prompt_id}.txt") 221 | File.write(file_path, content) 222 | end 223 | ``` 224 | 225 | ### Bulk Import 226 | 227 | ```ruby 228 | # Import multiple files 229 | Dir.glob('/old/prompts/*.txt').each do |file_path| 230 | prompt_id = File.basename(file_path, '.txt') 231 | content = File.read(file_path) 232 | 233 | prompt = PromptManager::Prompt.new(id: prompt_id) 234 | prompt.save(content) 235 | end 236 | ``` -------------------------------------------------------------------------------- /lib/prompt_manager/prompt.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/lib/prompt_manager/prompt.rb 2 | 3 | require_relative "directive_processor" 4 | 5 | class PromptManager::Prompt 6 | COMMENT_SIGNAL = '#' # lines beginning with this are a comment 7 | DIRECTIVE_SIGNAL = '//' # Like the old IBM JCL 8 | DEFAULT_PARAMETER_REGEX = /(\[[A-Z _|]+\])/ 9 | @parameter_regex = DEFAULT_PARAMETER_REGEX 10 | 11 | ############################################## 12 | ## Public class methods 13 | 14 | class << self 15 | attr_accessor :storage_adapter, :parameter_regex 16 | 17 | def get(id:) 18 | storage_adapter.get(id: id) # Return the hash directly from storage 19 | end 20 | 21 | def create(id:, text: "", parameters: {}) 22 | storage_adapter.save( 23 | id: id, 24 | text: text, 25 | parameters: parameters 26 | ) 27 | 28 | ::PromptManager::Prompt.new(id: id, context: [], directives_processor: PromptManager::DirectiveProcessor.new) 29 | end 30 | 31 | def find(id:) 32 | ::PromptManager::Prompt.new(id: id, context: [], directives_processor: PromptManager::DirectiveProcessor.new) 33 | end 34 | 35 | def destroy(id:) 36 | prompt = find(id: id) 37 | prompt.delete 38 | end 39 | 40 | def search(for_what) 41 | storage_adapter.search(for_what) 42 | end 43 | 44 | def method_missing(method_name, *args, &block) 45 | if storage_adapter.respond_to?(method_name) 46 | storage_adapter.send(method_name, *args, &block) 47 | else 48 | super 49 | end 50 | end 51 | 52 | def respond_to_missing?(method_name, include_private = false) 53 | storage_adapter.respond_to?(method_name, include_private) || super 54 | end 55 | end 56 | 57 | ############################################## 58 | ## Public Instance Methods 59 | 60 | attr_accessor :id, # String name for the prompt 61 | :text, # String, full text of the prompt 62 | :parameters # Hash, Key and Value are Strings 63 | 64 | 65 | def initialize( 66 | id: nil, # A String name for the prompt 67 | context: [], # TODO: Array of Strings or Pathname? 68 | directives_processor: PromptManager::DirectiveProcessor.new, 69 | external_binding: binding, 70 | erb_flag: false, # replace $ENVAR and ${ENVAR} when true 71 | envar_flag: false # process ERB against the external_binding when true 72 | ) 73 | 74 | @id = id 75 | @directives_processor = directives_processor 76 | 77 | validate_arguments(@id) 78 | 79 | @record = db.get(id: id) 80 | @text = @record[:text] || "" 81 | @parameters = @record[:parameters] || {} 82 | @directives = {} 83 | @external_binding = external_binding 84 | @erb_flag = erb_flag 85 | @envar_flag = envar_flag 86 | end 87 | 88 | def validate_arguments(prompt_id, prompts_db=db) 89 | raise ArgumentError, 'id cannot be blank' if prompt_id.nil? || prompt_id.strip.empty? 90 | raise(ArgumentError, 'storage_adapter is not set') if prompts_db.nil? 91 | end 92 | 93 | def to_s 94 | processed_text = remove_comments 95 | processed_text = substitute_values(processed_text, @parameters) 96 | processed_text = substitute_env_vars(processed_text) 97 | processed_text = process_directives(processed_text) 98 | process_erb(processed_text) 99 | end 100 | 101 | def save 102 | db.save( 103 | id: id, 104 | text: text, # Save the original text 105 | parameters: parameters 106 | ) 107 | end 108 | 109 | def delete = db.delete(id: id) 110 | 111 | 112 | ###################################### 113 | private 114 | 115 | def db = self.class.storage_adapter 116 | 117 | 118 | def remove_comments 119 | lines = @text.gsub(//m, '').lines(chomp: true) 120 | markdown_block_depth = 0 121 | filtered_lines = [] 122 | end_index = lines.index("__END__") || lines.size 123 | 124 | lines[0...end_index].each do |line| 125 | trimmed_line = line.strip 126 | 127 | if trimmed_line.start_with?('```') 128 | if trimmed_line == '```markdown' 129 | markdown_block_depth += 1 130 | elsif markdown_block_depth > 0 131 | markdown_block_depth -= 1 132 | end 133 | end 134 | 135 | if markdown_block_depth > 0 || !trimmed_line.start_with?(COMMENT_SIGNAL) 136 | filtered_lines << line 137 | end 138 | end 139 | 140 | filtered_lines.join("\n") 141 | end 142 | 143 | 144 | 145 | 146 | def substitute_values(input_text, values_hash) 147 | if values_hash.is_a?(Hash) && !values_hash.empty? 148 | values_hash.each do |key, value| 149 | value = value.last if value.is_a?(Array) 150 | input_text = input_text.gsub(key, value.nil? ? '' : value) 151 | end 152 | end 153 | input_text 154 | end 155 | 156 | def erb? = @erb_flag 157 | def envar? = @envar_flag 158 | 159 | def substitute_env_vars(input_text) 160 | return input_text unless envar? 161 | 162 | # First, handle shell command substitution $(command) 163 | input_text = input_text.gsub(/\$\(([^\)]+)\)/) do |match| 164 | cmd = $1.strip 165 | begin 166 | # Execute the shell command and capture its output 167 | result = `#{cmd}`.chomp 168 | result.empty? ? match : result 169 | rescue => e 170 | # If command execution fails, log the error and keep the original text 171 | warn "Shell command execution failed: #{e.message}" 172 | match 173 | end 174 | end 175 | 176 | # Then handle environment variables as before 177 | input_text.gsub(/\$(\w+)|\$\{(\w+)\}/) do |match| 178 | env_var = $1 || $2 179 | ENV[env_var] || match 180 | end 181 | end 182 | 183 | def process_directives(input_text) 184 | directive_lines = input_text.split("\n").select { |line| line.strip.start_with?(DIRECTIVE_SIGNAL) } 185 | @directives = directive_lines.each_with_object({}) { |line, hash| hash[line.strip] = "" } 186 | @directives = @directives_processor.run(@directives) 187 | substitute_values(input_text, @directives) 188 | end 189 | 190 | def process_erb(input_text) 191 | return input_text unless erb? 192 | 193 | ERB.new(input_text).result(@external_binding) 194 | end 195 | end 196 | -------------------------------------------------------------------------------- /test/prompt_manager/prompt_test.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/test/prompt_manager/prompt_test.rb 2 | 3 | require 'test_helper' 4 | require 'fileutils' 5 | require 'tmpdir' 6 | require 'pathname' 7 | 8 | debug_me{[ 9 | "PromptManager::Prompt.storage_adapter" 10 | ]} 11 | 12 | 13 | class PromptTest < Minitest::Test 14 | # Save original adapter settings to restore them after tests 15 | def setup 16 | # Save original settings 17 | @original_prompts_dir = PromptManager::Storage::FileSystemAdapter.prompts_dir 18 | @original_env = ENV.to_hash 19 | 20 | # Create a dedicated test directory for each test 21 | @test_dir = Dir.mktmpdir('prompt_test_') 22 | @test_prompts_dir = Pathname.new(File.join(@test_dir, 'prompts')) 23 | FileUtils.mkdir_p(@test_prompts_dir) 24 | 25 | # Temporarily change the prompts_dir for all tests in this run 26 | # We're using the same adapter class, just pointing it to a different directory 27 | PromptManager::Storage::FileSystemAdapter.prompts_dir = @test_prompts_dir 28 | end 29 | 30 | def teardown 31 | # Restore original adapter settings and clean up test directory 32 | PromptManager::Storage::FileSystemAdapter.prompts_dir = @original_prompts_dir 33 | ENV.replace(@original_env) 34 | 35 | FileUtils.remove_entry(@test_dir) if @test_dir && File.exist?(@test_dir) 36 | end 37 | 38 | def test_prompt_initialization_with_invalid_id 39 | assert_raises ArgumentError do 40 | PromptManager::Prompt.new(id: nil, context: [], directives_processor: PromptManager::DirectiveProcessor.new) 41 | end 42 | end 43 | 44 | def test_class_constants 45 | assert_equal '#', PromptManager::Prompt::COMMENT_SIGNAL 46 | assert_equal '//', PromptManager::Prompt::DIRECTIVE_SIGNAL 47 | end 48 | 49 | def test_prompt_initialization_raises_argument_error_when_id_blank 50 | assert_raises ArgumentError do 51 | PromptManager::Prompt.new(id: '', context: [], directives_processor: PromptManager::DirectiveProcessor.new) 52 | end 53 | end 54 | 55 | def test_prompt_initialization_raises_argument_error_when_no_storage_adapter_set 56 | original_adapter = PromptManager::Prompt.storage_adapter 57 | begin 58 | PromptManager::Prompt.storage_adapter = nil 59 | assert_raises(ArgumentError, 'storage_adapter is not set') do 60 | PromptManager::Prompt.new(id: 'test_prompt', context: [], directives_processor: PromptManager::DirectiveProcessor.new) 61 | end 62 | ensure 63 | PromptManager::Prompt.storage_adapter = original_adapter 64 | end 65 | end 66 | 67 | def test_prompt_initialization_with_valid_id 68 | # Create the test prompt files first 69 | create_test_prompt('test_prompt', 'Hello, World!', {}) 70 | 71 | prompt = PromptManager::Prompt.new(id: 'test_prompt', context: [], directives_processor: PromptManager::DirectiveProcessor.new) 72 | assert_equal 'test_prompt', prompt.id 73 | end 74 | 75 | def test_prompt_to_s_method 76 | # Create the test prompt files first 77 | create_test_prompt('test_prompt', 'Hello, World!', {}) 78 | 79 | prompt = PromptManager::Prompt.new(id: 'test_prompt', context: [], directives_processor: PromptManager::DirectiveProcessor.new) 80 | # Build removes comments and directives, but keeps __END__ etc. 81 | # EDIT: Now removes __END__ and subsequent lines. 82 | expected = "Hello, World!" 83 | assert_equal expected, prompt.to_s 84 | end 85 | 86 | def test_prompt_saves_to_storage 87 | new_prompt_id = 'new_prompt' 88 | new_prompt_text = "How are you, [NAME]?" 89 | new_prompt_parameters = { '[NAME]' => ['Rubyist'] } 90 | 91 | PromptManager::Prompt.create( 92 | id: new_prompt_id, 93 | text: new_prompt_text, 94 | parameters: new_prompt_parameters 95 | ) 96 | 97 | prompt_from_storage = PromptManager::Prompt.get(id: 'new_prompt') 98 | 99 | assert_equal new_prompt_text, prompt_from_storage[:text] 100 | assert_equal new_prompt_parameters, prompt_from_storage[:parameters] 101 | end 102 | 103 | def test_prompt_deletes_from_storage 104 | # Create a prompt first 105 | test_id = 'delete_test_prompt' 106 | create_test_prompt(test_id, 'Hello, I will be deleted', {}) 107 | 108 | prompt = PromptManager::Prompt.find(id: test_id) 109 | assert_equal test_id, prompt.id # Verify it exists 110 | 111 | prompt.delete 112 | 113 | assert_raises(ArgumentError) do 114 | PromptManager::Prompt.get(id: test_id) # Should raise error when prompt not found 115 | end 116 | end 117 | 118 | def test_prompt_searches_storage 119 | # Create multiple prompts to search through 120 | create_test_prompt('search_test_1', 'Hello, this is the first test prompt', {}) 121 | create_test_prompt('search_test_2', 'Goodbye, this is the second test prompt', {}) 122 | create_test_prompt('search_test_3', 'Hello again, this is the third test prompt', {}) 123 | 124 | # Search for a term that should match two prompts 125 | search_results = PromptManager::Prompt.search('Hello') 126 | 127 | refute_empty search_results 128 | assert_includes search_results, 'search_test_1' 129 | assert_includes search_results, 'search_test_3' 130 | refute_includes search_results, 'search_test_2' 131 | end 132 | 133 | private 134 | 135 | # Helper method to create test prompt files 136 | def create_test_prompt(id, text, parameters) 137 | # Get file extensions from the adapter 138 | prompt_ext = PromptManager::Storage::FileSystemAdapter.prompt_extension 139 | params_ext = PromptManager::Storage::FileSystemAdapter.params_extension 140 | 141 | # Create the prompt and parameter files in the test directory 142 | prompt_path = @test_prompts_dir.join("#{id}#{prompt_ext}") 143 | params_path = @test_prompts_dir.join("#{id}#{params_ext}") 144 | 145 | File.write(prompt_path, text) 146 | File.write(params_path, parameters.to_json) 147 | end 148 | 149 | 150 | def test_env_variable_replacement 151 | ENV['GREETING'] = 'Hello' 152 | prompt_text = 'Say $GREETING to world!' 153 | prompt = PromptManager::Prompt.new(prompt_text) 154 | result = prompt.process 155 | assert_equal 'Say Hello to world!', result 156 | end 157 | 158 | def test_erb_processing 159 | prompt_text = '2+2 is <%= 2+2 %>' 160 | prompt = PromptManager::Prompt.new(prompt_text) 161 | result = prompt.process 162 | assert_equal '2+2 is 4', result 163 | end 164 | 165 | def test_combined_features 166 | ENV['NAME'] = 'Alice' 167 | prompt_text = 'Hi, $NAME! Today, 3*3 equals <%= 3*3 %>.' 168 | prompt = PromptManager::Prompt.new(prompt_text) 169 | result = prompt.process 170 | assert_equal 'Hi, Alice! Today, 3*3 equals 9.', result 171 | end 172 | 173 | end 174 | 175 | __END__ 176 | -------------------------------------------------------------------------------- /test/prompt_manager/storage/file_system_adapter_test.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/test/prompt_manager/storage/file_system_adapter_test.rb 2 | 3 | require 'test_helper' 4 | 5 | require 'prompt_manager/storage/file_system_adapter' 6 | 7 | # Lets create a shortcut ... 8 | FSA = PromptManager::Storage::FileSystemAdapter 9 | 10 | 11 | class FileSystemAdapterTest < Minitest::Test 12 | def setup 13 | @prompts_dir = $PROMPTS_DIR # defined in test_helper 14 | @prompt_id = 'test_prompt' 15 | 16 | # An instance pf a stprage adapter class 17 | @adapter = FSA.config do |o| 18 | o.prompts_dir = $PROMPTS_DIR 19 | end.new 20 | directive_example_filename = 'directive_example' + PromptManager::Storage::FileSystemAdapter::PROMPT_EXTENSION 21 | directive_example_file = File.join(@prompts_dir, directive_example_filename) 22 | File.delete(directive_example_file) if File.exist?(directive_example_file) 23 | end 24 | 25 | def test_get_non_existent_prompt 26 | assert_raises ArgumentError do 27 | @adapter.get(id: 'non_existent') 28 | end 29 | end 30 | 31 | def test_delete_non_existent_prompt 32 | assert_raises Errno::ENOENT do 33 | @adapter.delete(id: 'non_existent') 34 | end 35 | end 36 | 37 | def test_save_with_invalid_id 38 | assert_raises Errno::ENOENT do 39 | @adapter.save(id: 'invalid/id', text: 'text', parameters: {}) 40 | end 41 | end 42 | 43 | 44 | def teardown 45 | # what should be torn down? 46 | end 47 | 48 | ############################################ 49 | def test_config 50 | assert_equal FSA, PromptManager::Storage::FileSystemAdapter 51 | 52 | assert FSA.respond_to? :config 53 | 54 | assert_equal FSA.prompts_dir, $PROMPTS_DIR 55 | # SMELL: assert_equal FSA.search_proc, FSA::SEARCH_PROC 56 | assert_equal FSA.prompt_extension, FSA::PROMPT_EXTENSION 57 | assert_equal FSA.params_extension, FSA::PARAMS_EXTENSION 58 | end 59 | 60 | 61 | def test_config_without_a_block 62 | assert_raises ArgumentError do 63 | FSA.config 64 | end 65 | end 66 | 67 | 68 | ############################################ 69 | def test_list 70 | assert FSA.respond_to? :list 71 | assert @adapter.respond_to? :list 72 | 73 | result = @adapter.list 74 | 75 | assert result.is_a?(Array) 76 | assert result.first.is_a?(String) 77 | assert result.include?('todo') 78 | assert result.include?('toy/8-ball') 79 | 80 | class_result = FSA.list 81 | 82 | assert class_result.is_a?(Array) 83 | assert class_result.first.is_a?(String) 84 | assert class_result.include?('todo') 85 | assert class_result.include?('toy/8-ball') 86 | end 87 | 88 | 89 | ############################################ 90 | def test_path 91 | assert FSA.respond_to? :path 92 | assert @adapter.respond_to? :path 93 | 94 | class_result = FSA.path('todo') 95 | result = @adapter.path('todo') 96 | 97 | assert_equal class_result, result 98 | 99 | assert_equal result.parent, @prompts_dir 100 | assert_equal result.extname.to_s, FSA.prompt_extension 101 | assert_equal result.basename.to_s.split('.').first, 'todo' 102 | end 103 | 104 | 105 | ############################################ 106 | def test_get 107 | # Setup 108 | expected_text = 'This is a prompt with [SIZE] and [COLOR].' 109 | expected_params = { 110 | '[SIZE]' => [20], 111 | '[COLOR]' => ['blue'] 112 | } 113 | 114 | prompt_path = @prompts_dir + (@prompt_id + FSA.prompt_extension) 115 | params_path = @prompts_dir + (@prompt_id + FSA.params_extension) 116 | 117 | prompt_path.write(expected_text) 118 | params_path.write(expected_params.to_json) 119 | 120 | # Exercise 121 | result = @adapter.get(id: @prompt_id) 122 | 123 | # Verify 124 | assert_equal expected_text, result[:text] 125 | assert_equal expected_params, result[:parameters] 126 | end 127 | 128 | 129 | ############################################ 130 | def test_save 131 | # Setup 132 | text = 'New prompt text' 133 | parameters = {difficulty: 'hard', time: 30} 134 | 135 | # Exercise 136 | @adapter.save(id: @prompt_id, text: text, parameters: parameters) 137 | 138 | # Verify 139 | assert File.exist?(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PROMPT_EXTENSION)) 140 | assert File.exist?(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PARAMS_EXTENSION)) 141 | assert_equal text, File.read(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PROMPT_EXTENSION)) 142 | assert_equal parameters, JSON.parse(File.read(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PARAMS_EXTENSION)), symbolize_names: true) 143 | end 144 | 145 | 146 | ############################################ 147 | def test_delete 148 | # Setup 149 | # Creating the files to be deleted 150 | File.write(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PROMPT_EXTENSION), 'To be deleted') 151 | File.write(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PARAMS_EXTENSION), {to_be: 'deleted'}.to_json) 152 | 153 | # Exercise 154 | @adapter.delete(id: @prompt_id) 155 | 156 | # Verify 157 | refute File.exist?(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PROMPT_EXTENSION)) 158 | refute File.exist?(File.join(@prompts_dir, @prompt_id + PromptManager::Storage::FileSystemAdapter::PARAMS_EXTENSION)) 159 | end 160 | 161 | 162 | ############################################ 163 | def test_search_proc 164 | search_term = "MadBomber" 165 | saved_search_proc = @adapter.class.search_proc 166 | 167 | # search_proc is a way to use command line tools like 168 | # grep, rg, aq, ack, etc or anything else that makes 169 | # sense that will return a list of prompt IDs. 170 | # In the case of the FileSystemAdapter the ID is 171 | # the basename of the file snns its extension. 172 | @adapter.class.search_proc = ->(q) { ["hello #{q}"] } 173 | 174 | expected = ["hello madbomber"] # NOTE: query term is all lowercase 175 | results = @adapter.search(search_term) 176 | 177 | assert_equal expected, results 178 | 179 | @adapter.class.search_proc = saved_search_proc 180 | end 181 | 182 | 183 | ############################################ 184 | def test_search 185 | search_term = "hello" 186 | 187 | expected = %w[ 188 | also_included 189 | hello_prompt 190 | included 191 | test2_prompt 192 | ].sort 193 | 194 | # Exercise 195 | results = @adapter.search(search_term) 196 | 197 | # Verify 198 | assert_equal expected, results 199 | refute_includes results, 'excluded' 200 | end 201 | 202 | # Add more tests for exceptional cases and edge conditions 203 | end 204 | -------------------------------------------------------------------------------- /docs/getting-started/quick-start.md: -------------------------------------------------------------------------------- 1 | # Quick Start 2 | 3 | This guide will get you up and running with PromptManager in just a few minutes. 4 | 5 | ## 1. Install PromptManager 6 | 7 | ```bash 8 | gem install prompt_manager 9 | ``` 10 | 11 | ## 2. Set Up Your First Prompt 12 | 13 | Create a directory for your prompts and your first prompt file: 14 | 15 | ```bash 16 | mkdir ~/.prompts 17 | ``` 18 | 19 | Create your first prompt file: 20 | 21 | === "~/.prompts/greeting.txt" 22 | 23 | ```text 24 | # Description: A friendly greeting prompt 25 | # Keywords: NAME, LANGUAGE 26 | 27 | Hello [NAME]! 28 | 29 | I'm here to help you today. Please let me know how I can assist you, 30 | and I'll respond in [LANGUAGE]. 31 | 32 | What would you like to know about? 33 | ``` 34 | 35 | === "~/.prompts/greeting.json" 36 | 37 | ```json 38 | { 39 | "[NAME]": ["Alice", "Bob", "Charlie"], 40 | "[LANGUAGE]": ["English", "Spanish", "French"] 41 | } 42 | ``` 43 | 44 | ## 3. Basic Usage 45 | 46 | Create a simple Ruby script to use your prompt: 47 | 48 | ```ruby title="quick_example.rb" 49 | #!/usr/bin/env ruby 50 | 51 | require 'prompt_manager' 52 | 53 | # Configure the FileSystem storage adapter 54 | PromptManager::Prompt.storage_adapter = 55 | PromptManager::Storage::FileSystemAdapter.config do |config| 56 | config.prompts_dir = File.expand_path('~/.prompts') 57 | end.new 58 | 59 | # Load your prompt 60 | prompt = PromptManager::Prompt.new(id: 'greeting') 61 | 62 | # Set parameter values 63 | prompt.parameters = { 64 | "[NAME]" => "Alice", 65 | "[LANGUAGE]" => "English" 66 | } 67 | 68 | # Generate the final prompt text 69 | puts "=== Generated Prompt ===" 70 | puts prompt.to_s 71 | 72 | # Save any parameter changes 73 | prompt.save 74 | ``` 75 | 76 | Run it: 77 | 78 | ```bash 79 | ruby quick_example.rb 80 | ``` 81 | 82 | Expected output: 83 | ``` 84 | === Generated Prompt === 85 | Hello Alice! 86 | 87 | I'm here to help you today. Please let me know how I can assist you, 88 | and I'll respond in English. 89 | 90 | What would you like to know about? 91 | ``` 92 | 93 | ## 4. Understanding the Workflow 94 | 95 | The basic PromptManager workflow involves: 96 | 97 | ```mermaid 98 | graph LR 99 | A[Create Prompt File] --> B[Configure Storage] 100 | B --> C[Load Prompt] 101 | C --> D[Set Parameters] 102 | D --> E[Generate Text] 103 | E --> F[Save Changes] 104 | ``` 105 | 106 | ### Step by Step: 107 | 108 | 1. **Create Prompt File**: Write your template with `[KEYWORDS]` 109 | 2. **Configure Storage**: Choose FileSystem or ActiveRecord adapter 110 | 3. **Load Prompt**: Create a Prompt instance with an ID 111 | 4. **Set Parameters**: Provide values for your keywords 112 | 5. **Generate Text**: Call `to_s` to get the final prompt 113 | 6. **Save Changes**: Persist parameter updates 114 | 115 | ## 5. Advanced Quick Start 116 | 117 | Here's a more advanced example showing multiple features: 118 | 119 | ```ruby title="advanced_example.rb" 120 | require 'prompt_manager' 121 | 122 | # Configure storage 123 | PromptManager::Prompt.storage_adapter = 124 | PromptManager::Storage::FileSystemAdapter.config do |config| 125 | config.prompts_dir = File.expand_path('~/.prompts') 126 | end.new 127 | 128 | # Create a prompt with directives and ERB 129 | prompt = PromptManager::Prompt.new( 130 | id: 'advanced_greeting', 131 | erb_flag: true, 132 | envar_flag: true 133 | ) 134 | 135 | # Set parameters 136 | prompt.parameters = { 137 | "[USER_NAME]" => "Alice", 138 | "[TASK_TYPE]" => "translation", 139 | "[URGENCY]" => "high" 140 | } 141 | 142 | # Display available keywords 143 | puts "Available keywords: #{prompt.keywords.join(', ')}" 144 | 145 | # Generate and display the result 146 | puts "\n=== Final Prompt ===" 147 | puts prompt.to_s 148 | 149 | # Save changes 150 | prompt.save 151 | puts "\nPrompt saved successfully!" 152 | ``` 153 | 154 | === "~/.prompts/advanced_greeting.txt" 155 | 156 | ```text 157 | # Advanced greeting with directives and ERB 158 | //include common/header.txt 159 | 160 | Dear [USER_NAME], 161 | 162 | <% if '[URGENCY]' == 'high' %> 163 | 🚨 URGENT: This [TASK_TYPE] request requires immediate attention. 164 | <% else %> 165 | 📋 Standard [TASK_TYPE] request for processing. 166 | <% end %> 167 | 168 | Current system time: <%= Time.now.strftime('%Y-%m-%d %H:%M:%S') %> 169 | Working directory: <%= Dir.pwd %> 170 | 171 | __END__ 172 | This section is ignored - useful for notes and documentation. 173 | ``` 174 | 175 | ## 6. Next Steps 176 | 177 | Now that you have PromptManager working, explore these areas: 178 | 179 | ### Learn Core Features 180 | - [Parameterized Prompts](../core-features/parameterized-prompts.md) - Master keyword substitution 181 | - [Directive Processing](../core-features/directive-processing.md) - Include files and process commands 182 | - [ERB Integration](../core-features/erb-integration.md) - Dynamic templating 183 | 184 | ### Storage Options 185 | - [FileSystem Adapter](../storage/filesystem-adapter.md) - File-based storage 186 | - [ActiveRecord Adapter](../storage/activerecord-adapter.md) - Database storage 187 | - [Custom Adapters](../storage/custom-adapters.md) - Build your own 188 | 189 | ### Advanced Usage 190 | - [Custom Keywords](../advanced/custom-keywords.md) - Define your own keyword patterns 191 | - [Search Integration](../advanced/search-integration.md) - Find prompts quickly 192 | - [Performance Tips](../advanced/performance.md) - Optimize for large collections 193 | 194 | ### Real Examples 195 | - [Basic Examples](../examples/basic.md) - Simple use cases 196 | - [Advanced Examples](../examples/advanced.md) - Complex scenarios 197 | - [Real World Cases](../examples/real-world.md) - Production examples 198 | 199 | ## Common Patterns 200 | 201 | Here are some common patterns you'll use frequently: 202 | 203 | ### Parameter History 204 | ```ruby 205 | # Access parameter history (since v0.3.0) 206 | prompt.parameters["[NAME]"] # Returns ["Alice", "Bob", "Charlie"] 207 | latest_name = prompt.parameters["[NAME]"].last # "Charlie" 208 | ``` 209 | 210 | ### Error Handling 211 | ```ruby 212 | begin 213 | prompt = PromptManager::Prompt.new(id: 'missing') 214 | rescue PromptManager::StorageError => e 215 | puts "Storage error: #{e.message}" 216 | rescue PromptManager::ParameterError => e 217 | puts "Parameter error: #{e.message}" 218 | end 219 | ``` 220 | 221 | ### Search and Discovery 222 | ```ruby 223 | # List all available prompts 224 | prompts = PromptManager::Prompt.list 225 | puts "Available prompts: #{prompts.join(', ')}" 226 | 227 | # Search for prompts (requires search_proc configuration) 228 | results = PromptManager::Prompt.search('greeting') 229 | ``` 230 | 231 | ## Troubleshooting 232 | 233 | ### File Not Found 234 | If you get "file not found" errors, check: 235 | 236 | 1. **Prompt directory exists**: `ls ~/.prompts` 237 | 2. **File has correct extension**: Should be `.txt` by default 238 | 3. **Prompt ID matches filename**: `greeting` looks for `greeting.txt` 239 | 240 | ### Parameter Errors 241 | If parameters aren't substituting: 242 | 243 | 1. **Check keyword format**: Must be `[UPPERCASE]` by default 244 | 2. **Verify parameter keys match**: Case-sensitive matching 245 | 3. **Ensure parameters are set**: Call `prompt.parameters = {...}` 246 | 247 | ### Permission Issues 248 | If you can't write to the prompts directory: 249 | 250 | ```bash 251 | chmod 755 ~/.prompts 252 | chmod 644 ~/.prompts/*.txt 253 | chmod 644 ~/.prompts/*.json 254 | ``` 255 | 256 | Need help? Check our [testing guide](../development/testing.md) or [open an issue](https://github.com/MadBomber/prompt_manager/issues). -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # PromptManager Documentation 2 | 3 |
4 | ⚠️ CAUTION ⚠️
5 | Breaking Changes are Coming
6 | See Roadmap for details 7 |
8 | 9 |
10 | 11 | 12 | 15 | 33 | 34 |
13 | PromptManager - The Enchanted Librarian of AI Prompts 14 | 16 |

Like an enchanted librarian organizing floating books of knowledge, PromptManager helps you masterfully orchestrate and organize your AI prompts through wisdom and experience.

17 | 18 |

Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships.

19 | 20 |

Key Features

21 | 32 |
35 |
36 | 37 | ## What is PromptManager? 38 | 39 | PromptManager is a Ruby gem designed for managing parameterized prompts used in generative AI applications. It provides a sophisticated system for organizing, templating, and processing prompts with support for multiple storage backends, directive processing, and advanced templating features. 40 | 41 | Think of it as your personal AI prompt librarian - organizing your prompts, managing their parameters, processing their directives, and ensuring they're always ready when you need them. 42 | 43 | ## Quick Start 44 | 45 | Get up and running with PromptManager in minutes: 46 | 47 | === "Installation" 48 | 49 | ```bash 50 | gem install prompt_manager 51 | # or add to Gemfile 52 | bundle add prompt_manager 53 | ``` 54 | 55 | === "Basic Usage" 56 | 57 | ```ruby 58 | require 'prompt_manager' 59 | 60 | # Configure storage 61 | PromptManager::Prompt.storage_adapter = 62 | PromptManager::Storage::FileSystemAdapter.config do |config| 63 | config.prompts_dir = '~/.prompts' 64 | end.new 65 | 66 | # Use a prompt 67 | prompt = PromptManager::Prompt.new(id: 'greeting') 68 | prompt.parameters = { 69 | "[NAME]" => "Alice", 70 | "[LANGUAGE]" => "English" 71 | } 72 | 73 | puts prompt.to_s 74 | ``` 75 | 76 | === "Create a Prompt" 77 | 78 | ```text 79 | # ~/.prompts/greeting.txt 80 | # Description: A friendly greeting prompt 81 | 82 | Hello [NAME]! How can I assist you today? 83 | Please respond in [LANGUAGE]. 84 | ``` 85 | 86 | ## Architecture Overview 87 | 88 | PromptManager follows a modular architecture designed for flexibility and extensibility: 89 | 90 | ```mermaid 91 | graph TB 92 | subgraph "Application Layer" 93 | A[Your Application] 94 | P[PromptManager::Prompt] 95 | end 96 | 97 | subgraph "Processing Layer" 98 | D[Directive Processor] 99 | E[ERB Engine] 100 | K[Keyword Substitution] 101 | end 102 | 103 | subgraph "Storage Layer" 104 | FS[FileSystem Adapter] 105 | AR[ActiveRecord Adapter] 106 | CA[Custom Adapter] 107 | end 108 | 109 | A --> P 110 | P --> D 111 | P --> E 112 | P --> K 113 | P --> FS 114 | P --> AR 115 | P --> CA 116 | 117 | D --> |includes| FS 118 | E --> |templates| P 119 | K --> |substitutes| P 120 | ``` 121 | 122 | ## Core Concepts 123 | 124 | ### Parameterized Prompts 125 | 126 | Transform static prompts into dynamic templates: 127 | 128 | ```ruby 129 | # Template with parameters 130 | prompt_text = "Translate '[TEXT]' from [SOURCE_LANG] to [TARGET_LANG]" 131 | 132 | # Filled with values 133 | prompt.parameters = { 134 | "[TEXT]" => "Hello world", 135 | "[SOURCE_LANG]" => "English", 136 | "[TARGET_LANG]" => "Spanish" 137 | } 138 | 139 | # Result: "Translate 'Hello world' from English to Spanish" 140 | ``` 141 | 142 | ### Directive Processing 143 | 144 | Use JCL-style directives for prompt composition: 145 | 146 | ```text 147 | # Common header for all customer service prompts 148 | //include common/customer_service_header.txt 149 | 150 | # Dynamic template inclusion 151 | //include templates/[TEMPLATE_TYPE].txt 152 | 153 | Handle this customer inquiry about [TOPIC]. 154 | ``` 155 | 156 | ### Storage Adapters 157 | 158 | Choose your preferred storage backend: 159 | 160 | - **FileSystemAdapter**: Store prompts as text files 161 | - **ActiveRecordAdapter**: Store prompts in a database 162 | - **Custom Adapters**: Build your own storage solution 163 | 164 | ## Why PromptManager? 165 | 166 | ### 🎯 **Organized Prompts** 167 | Keep your prompts organized in a structured, searchable format instead of scattered across your codebase. 168 | 169 | ### 🔄 **Reusable Templates** 170 | Create parameterized templates that can be reused across different contexts and applications. 171 | 172 | ### 🛠️ **Powerful Processing** 173 | Advanced features like directive processing, ERB templating, and environment variable substitution. 174 | 175 | ### 📈 **Scalable Architecture** 176 | Modular design supports everything from simple scripts to enterprise applications. 177 | 178 | ### 🔍 **Easy Management** 179 | Built-in search capabilities and parameter history make prompt management effortless. 180 | 181 | ## Getting Started 182 | 183 | Ready to dive in? Here are some great places to start: 184 | 185 |
186 | 187 | - :fontawesome-solid-rocket:{ .lg .middle } __Quick Start__ 188 | 189 | --- 190 | 191 | Get PromptManager running in your project within minutes 192 | 193 | [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md) 194 | 195 | - :fontawesome-solid-book:{ .lg .middle } __Core Features__ 196 | 197 | --- 198 | 199 | Learn about parameterized prompts, directives, and more 200 | 201 | [:octicons-arrow-right-24: Core Features](core-features/parameterized-prompts.md) 202 | 203 | - :fontawesome-solid-database:{ .lg .middle } __Storage Adapters__ 204 | 205 | --- 206 | 207 | Choose the right storage solution for your needs 208 | 209 | [:octicons-arrow-right-24: Storage Options](storage/overview.md) 210 | 211 | - :fontawesome-solid-code:{ .lg .middle } __API Reference__ 212 | 213 | --- 214 | 215 | Complete reference for all classes and methods 216 | 217 | [:octicons-arrow-right-24: API Docs](api/prompt-class.md) 218 | 219 |
220 | 221 | ## Community & Support 222 | 223 | - **GitHub**: [MadBomber/prompt_manager](https://github.com/MadBomber/prompt_manager) 224 | - **RubyGems**: [prompt_manager](https://rubygems.org/gems/prompt_manager) 225 | - **Issues**: [Report bugs or request features](https://github.com/MadBomber/prompt_manager/issues) 226 | - **Discussions**: [Community discussions](https://github.com/MadBomber/prompt_manager/discussions) 227 | 228 | ## License 229 | 230 | PromptManager is released under the [MIT License](https://opensource.org/licenses/MIT). -------------------------------------------------------------------------------- /docs/api/prompt-class.md: -------------------------------------------------------------------------------- 1 | # Prompt Class API Reference 2 | 3 | The `PromptManager::Prompt` class is the core interface for working with prompts in PromptManager. 4 | 5 | ## Class Methods 6 | 7 | ### `new(id:, **options)` 8 | 9 | Creates a new Prompt instance. 10 | 11 | **Parameters:** 12 | - `id` (String): Unique identifier for the prompt 13 | - `options` (Hash): Optional configuration parameters 14 | 15 | **Options:** 16 | - `erb_flag` (Boolean): Enable ERB template processing (default: false) 17 | - `envar_flag` (Boolean): Enable environment variable substitution (default: false) 18 | - `storage` (Storage::Base): Custom storage adapter (default: configured adapter) 19 | 20 | **Returns:** `PromptManager::Prompt` instance 21 | 22 | **Examples:** 23 | 24 | ```ruby 25 | # Basic prompt 26 | prompt = PromptManager::Prompt.new(id: 'welcome_message') 27 | 28 | # With ERB processing 29 | prompt = PromptManager::Prompt.new( 30 | id: 'dynamic_prompt', 31 | erb_flag: true 32 | ) 33 | 34 | # With environment variables 35 | prompt = PromptManager::Prompt.new( 36 | id: 'system_prompt', 37 | envar_flag: true 38 | ) 39 | 40 | # All options 41 | prompt = PromptManager::Prompt.new( 42 | id: 'advanced_prompt', 43 | erb_flag: true, 44 | envar_flag: true 45 | ) 46 | ``` 47 | 48 | ## Instance Methods 49 | 50 | ### `render(parameters = {})` 51 | 52 | Renders the prompt with the provided parameters. 53 | 54 | **Parameters:** 55 | - `parameters` (Hash): Key-value pairs for parameter substitution 56 | 57 | **Returns:** String - The rendered prompt content 58 | 59 | **Raises:** 60 | - `PromptNotFoundError` - If the prompt file cannot be found 61 | - `MissingParametersError` - If required parameters are not provided 62 | - `DirectiveProcessingError` - If directive processing fails 63 | 64 | **Examples:** 65 | 66 | ```ruby 67 | # Basic rendering 68 | result = prompt.render 69 | 70 | # With parameters 71 | result = prompt.render( 72 | customer_name: 'John Doe', 73 | order_id: 'ORD-123' 74 | ) 75 | 76 | # With complex parameters 77 | result = prompt.render( 78 | user: { 79 | name: 'Alice', 80 | email: 'alice@example.com' 81 | }, 82 | items: ['Item 1', 'Item 2'], 83 | total: 99.99 84 | ) 85 | ``` 86 | 87 | ### `save(content, **metadata)` 88 | 89 | Saves prompt content to storage. 90 | 91 | **Parameters:** 92 | - `content` (String): The prompt content to save 93 | - `metadata` (Hash): Optional metadata to store with the prompt 94 | 95 | **Returns:** Boolean - Success status 96 | 97 | **Examples:** 98 | 99 | ```ruby 100 | # Save content 101 | prompt.save("Hello [NAME], welcome to our service!") 102 | 103 | # Save with metadata 104 | prompt.save( 105 | "Your order [ORDER_ID] is ready!", 106 | category: 'notifications', 107 | author: 'system', 108 | version: '1.0' 109 | ) 110 | ``` 111 | 112 | ### `content` 113 | 114 | Retrieves the raw prompt content from storage. 115 | 116 | **Returns:** String - The raw prompt content 117 | 118 | **Example:** 119 | 120 | ```ruby 121 | raw_content = prompt.content 122 | puts raw_content # "Hello [NAME]!" 123 | ``` 124 | 125 | ### `parameters` 126 | 127 | Extracts parameter names from the prompt content. 128 | 129 | **Returns:** Array - List of parameter names found in the prompt 130 | 131 | **Example:** 132 | 133 | ```ruby 134 | # Prompt content: "Hello [NAME], your order [ORDER_ID] is ready!" 135 | params = prompt.parameters 136 | puts params # ['NAME', 'ORDER_ID'] 137 | ``` 138 | 139 | ### `delete` 140 | 141 | Removes the prompt from storage. 142 | 143 | **Returns:** Boolean - Success status 144 | 145 | **Example:** 146 | 147 | ```ruby 148 | prompt.delete 149 | ``` 150 | 151 | ### `exists?` 152 | 153 | Checks if the prompt exists in storage. 154 | 155 | **Returns:** Boolean - True if prompt exists 156 | 157 | **Example:** 158 | 159 | ```ruby 160 | if prompt.exists? 161 | puts "Prompt found" 162 | else 163 | puts "Prompt not found" 164 | end 165 | ``` 166 | 167 | ## Properties 168 | 169 | ### `id` 170 | 171 | **Type:** String (read-only) 172 | 173 | The unique identifier for the prompt. 174 | 175 | ```ruby 176 | prompt = PromptManager::Prompt.new(id: 'welcome') 177 | puts prompt.id # "welcome" 178 | ``` 179 | 180 | ### `erb_flag` 181 | 182 | **Type:** Boolean 183 | 184 | Whether ERB processing is enabled. 185 | 186 | ```ruby 187 | prompt.erb_flag = true 188 | ``` 189 | 190 | ### `envar_flag` 191 | 192 | **Type:** Boolean 193 | 194 | Whether environment variable substitution is enabled. 195 | 196 | ```ruby 197 | prompt.envar_flag = true 198 | ``` 199 | 200 | ### `storage` 201 | 202 | **Type:** Storage::Base 203 | 204 | The storage adapter used by this prompt. 205 | 206 | ```ruby 207 | prompt.storage = PromptManager::Storage::FileSystemAdapter.new 208 | ``` 209 | 210 | ## Parameter Processing 211 | 212 | ### Parameter Syntax 213 | 214 | Parameters use square bracket syntax: `[PARAMETER_NAME]` 215 | 216 | ```ruby 217 | # In prompt file: 218 | # "Hello [NAME], your balance is $[BALANCE]" 219 | 220 | prompt.render( 221 | name: 'Alice', 222 | balance: 1500.00 223 | ) 224 | # Result: "Hello Alice, your balance is $1500.0" 225 | ``` 226 | 227 | ### Nested Parameters 228 | 229 | Parameters can reference nested hash values: 230 | 231 | ```ruby 232 | # In prompt file: 233 | # "User: [USER.NAME] ([USER.EMAIL])" 234 | 235 | prompt.render( 236 | user: { 237 | name: 'Bob', 238 | email: 'bob@example.com' 239 | } 240 | ) 241 | # Result: "User: Bob (bob@example.com)" 242 | ``` 243 | 244 | ### Array Parameters 245 | 246 | Arrays are joined with commas by default: 247 | 248 | ```ruby 249 | # In prompt file: 250 | # "Items: [ITEMS]" 251 | 252 | prompt.render(items: ['Apple', 'Banana', 'Orange']) 253 | # Result: "Items: Apple, Banana, Orange" 254 | ``` 255 | 256 | ## Error Handling 257 | 258 | ### Exception Hierarchy 259 | 260 | ```ruby 261 | PromptManager::Error 262 | ├── PromptNotFoundError 263 | ├── MissingParametersError 264 | ├── DirectiveProcessingError 265 | └── StorageError 266 | ``` 267 | 268 | ### Error Details 269 | 270 | ```ruby 271 | begin 272 | prompt.render 273 | rescue PromptManager::MissingParametersError => e 274 | puts e.message # Human readable message 275 | puts e.missing_parameters # Array of missing parameter names 276 | puts e.prompt_id # ID of the prompt that failed 277 | rescue PromptManager::DirectiveProcessingError => e 278 | puts e.message # Error details 279 | puts e.line_number # Line where error occurred (if available) 280 | puts e.directive # The directive that failed 281 | end 282 | ``` 283 | 284 | ## Threading and Concurrency 285 | 286 | ### Thread Safety 287 | 288 | Prompt instances are **not** thread-safe. Create separate instances for each thread: 289 | 290 | ```ruby 291 | # Thread-safe usage 292 | threads = [] 293 | (1..10).each do |i| 294 | threads << Thread.new do 295 | # Each thread gets its own instance 296 | prompt = PromptManager::Prompt.new(id: 'worker_prompt') 297 | result = prompt.render(worker_id: i) 298 | puts result 299 | end 300 | end 301 | 302 | threads.each(&:join) 303 | ``` 304 | 305 | ### Shared Storage 306 | 307 | Storage adapters handle their own thread safety. Multiple Prompt instances can safely share the same storage adapter. 308 | 309 | ## Best Practices 310 | 311 | ### Instance Reuse 312 | 313 | ```ruby 314 | # Good: Reuse instances when possible 315 | prompt = PromptManager::Prompt.new(id: 'email_template') 316 | 317 | customers.each do |customer| 318 | email_content = prompt.render( 319 | name: customer.name, 320 | email: customer.email 321 | ) 322 | send_email(customer, email_content) 323 | end 324 | ``` 325 | 326 | ### Parameter Validation 327 | 328 | ```ruby 329 | # Validate parameters before rendering 330 | required_params = prompt.parameters 331 | missing_params = required_params - params.keys 332 | 333 | unless missing_params.empty? 334 | raise "Missing parameters: #{missing_params.join(', ')}" 335 | end 336 | 337 | result = prompt.render(params) 338 | ``` 339 | 340 | ### Error Recovery 341 | 342 | ```ruby 343 | def safe_render(prompt_id, params = {}) 344 | prompt = PromptManager::Prompt.new(id: prompt_id) 345 | prompt.render(params) 346 | rescue PromptManager::PromptNotFoundError 347 | "Default message when prompt unavailable" 348 | rescue PromptManager::MissingParametersError => e 349 | "Missing: #{e.missing_parameters.join(', ')}" 350 | rescue => e 351 | Rails.logger.error "Prompt render error: #{e.message}" 352 | "An error occurred" 353 | end 354 | ``` -------------------------------------------------------------------------------- /docs/getting-started/basic-concepts.md: -------------------------------------------------------------------------------- 1 | # Basic Concepts 2 | 3 | Understanding these core concepts will help you make the most of PromptManager. 4 | 5 | ## The Prompt Lifecycle 6 | 7 | Every prompt in PromptManager follows a predictable lifecycle: 8 | 9 | ```mermaid 10 | graph TD 11 | A[Create/Load Prompt] --> B[Parse Keywords] 12 | B --> C[Set Parameters] 13 | C --> D[Process Directives] 14 | D --> E[Apply ERB Templates] 15 | E --> F[Substitute Variables] 16 | F --> G[Generate Final Text] 17 | G --> H[Save Changes] 18 | ``` 19 | 20 | ## Core Components 21 | 22 | ### 1. Prompts 23 | 24 | A **Prompt** is the central entity in PromptManager. It represents a template with: 25 | 26 | - **Text content** with embedded keywords 27 | - **Parameters** (values for keywords) 28 | - **Metadata** (directives, comments, configuration) 29 | 30 | ```ruby 31 | prompt = PromptManager::Prompt.new( 32 | id: 'example', # Unique identifier 33 | erb_flag: true, # Enable ERB processing 34 | envar_flag: true # Enable environment variables 35 | ) 36 | ``` 37 | 38 | ### 2. Keywords 39 | 40 | **Keywords** are placeholders in your prompt text that get replaced with actual values: 41 | 42 | ```text 43 | Hello [NAME], today is [DATE] and the weather is [WEATHER]. 44 | ``` 45 | 46 | Default keyword format: `[UPPERCASE_WITH_UNDERSCORES]` 47 | 48 | You can customize this pattern: 49 | 50 | ```ruby 51 | # Use {{mustache}} style 52 | PromptManager::Prompt.parameter_regex = /(\{\{[a-z_]+\}\})/ 53 | 54 | # Use :symbol style 55 | PromptManager::Prompt.parameter_regex = /(:[a-z_]+)/ 56 | ``` 57 | 58 | ### 3. Parameters 59 | 60 | **Parameters** are the actual values that replace keywords: 61 | 62 | ```ruby 63 | prompt.parameters = { 64 | "[NAME]" => "Alice", 65 | "[DATE]" => Date.today.to_s, 66 | "[WEATHER]" => "sunny" 67 | } 68 | ``` 69 | 70 | Since v0.3.0, parameters store history as arrays: 71 | 72 | ```ruby 73 | prompt.parameters = { 74 | "[NAME]" => ["Alice", "Bob", "Charlie"] # Charlie is most recent 75 | } 76 | ``` 77 | 78 | ### 4. Storage Adapters 79 | 80 | **Storage Adapters** handle how prompts are persisted: 81 | 82 | === "FileSystem" 83 | 84 | ```ruby 85 | PromptManager::Storage::FileSystemAdapter.config do |config| 86 | config.prompts_dir = '~/.prompts' 87 | config.prompt_extension = '.txt' 88 | config.params_extension = '.json' 89 | end 90 | ``` 91 | 92 | === "ActiveRecord" 93 | 94 | ```ruby 95 | PromptManager::Storage::ActiveRecordAdapter.config do |config| 96 | config.model = PromptModel 97 | config.id_column = :name 98 | config.text_column = :content 99 | config.parameters_column = :params 100 | end 101 | ``` 102 | 103 | ### 5. Directives 104 | 105 | **Directives** are special instructions that start with `//`: 106 | 107 | ```text 108 | //include common/header.txt 109 | //import templates/[TEMPLATE_TYPE].txt 110 | 111 | Your main prompt content here... 112 | ``` 113 | 114 | ## File Structure (FileSystem Adapter) 115 | 116 | When using the FileSystem adapter, your prompts are organized like this: 117 | 118 | ``` 119 | ~/.prompts/ 120 | ├── greeting.txt # Prompt text 121 | ├── greeting.json # Parameters 122 | ├── translation.txt 123 | ├── translation.json 124 | └── common/ 125 | ├── header.txt # Shared components 126 | └── footer.txt 127 | ``` 128 | 129 | ### Prompt Files (`.txt`) 130 | 131 | ```text title="greeting.txt" 132 | # Description: Friendly greeting prompt 133 | # Tags: customer-service, greeting 134 | # Version: 1.2 135 | 136 | //include common/header.txt 137 | 138 | Hello [CUSTOMER_NAME]! 139 | 140 | Thank you for contacting [COMPANY_NAME]. I'm here to help you with 141 | [REQUEST_TYPE]. Let me know how I can assist you today. 142 | 143 | Best regards, 144 | [AGENT_NAME] 145 | 146 | __END__ 147 | Internal notes: This prompt is used for all initial customer contacts. 148 | Update the company name parameter when client changes. 149 | ``` 150 | 151 | ### Parameter Files (`.json`) 152 | 153 | ```json title="greeting.json" 154 | { 155 | "[CUSTOMER_NAME]": ["Alice Johnson", "Bob Smith"], 156 | "[COMPANY_NAME]": ["Acme Corp"], 157 | "[REQUEST_TYPE]": ["general inquiry", "technical support", "billing"], 158 | "[AGENT_NAME]": ["Sarah", "Mike", "Jennifer"] 159 | } 160 | ``` 161 | 162 | ## Processing Pipeline 163 | 164 | PromptManager processes prompts through several stages: 165 | 166 | ### 1. Text Loading 167 | - Load raw prompt text from storage 168 | - Parse out comments and `__END__` sections 169 | 170 | ### 2. Keyword Extraction 171 | - Scan text for keyword patterns 172 | - Build list of required parameters 173 | 174 | ### 3. Directive Processing 175 | - Process `//include` and `//import` directives 176 | - Handle loop protection for circular includes 177 | - Substitute keywords in directive paths 178 | 179 | ### 4. Template Processing 180 | - Apply ERB templates if `erb_flag` is true 181 | - Substitute environment variables if `envar_flag` is true 182 | 183 | ### 5. Parameter Substitution 184 | - Replace keywords with parameter values 185 | - Handle missing parameters (error or warning) 186 | 187 | ### 6. Final Assembly 188 | - Combine processed components 189 | - Return final prompt text 190 | 191 | ## Error Handling 192 | 193 | PromptManager provides specific error types: 194 | 195 | ```ruby 196 | begin 197 | prompt = PromptManager::Prompt.new(id: 'example') 198 | puts prompt.to_s 199 | rescue PromptManager::StorageError => e 200 | puts "Storage problem: #{e.message}" 201 | rescue PromptManager::ParameterError => e 202 | puts "Parameter issue: #{e.message}" 203 | rescue PromptManager::ConfigurationError => e 204 | puts "Config problem: #{e.message}" 205 | end 206 | ``` 207 | 208 | ### Common Error Scenarios 209 | 210 | | Error Type | Common Cause | Solution | 211 | |------------|--------------|----------| 212 | | `StorageError` | File not found, permission denied | Check file paths and permissions | 213 | | `ParameterError` | Missing parameter value | Set all required parameters | 214 | | `ConfigurationError` | Invalid adapter config | Review adapter configuration | 215 | 216 | ## Best Practices 217 | 218 | ### 1. Organize Your Prompts 219 | 220 | ``` 221 | prompts/ 222 | ├── common/ # Shared components 223 | │ ├── headers/ 224 | │ ├── footers/ 225 | │ └── signatures/ 226 | ├── customer-service/ # Domain-specific prompts 227 | ├── technical/ 228 | └── templates/ # Reusable templates 229 | ``` 230 | 231 | ### 2. Use Meaningful Keywords 232 | 233 | ```text 234 | # Good - descriptive and clear 235 | [CUSTOMER_NAME], [ORDER_NUMBER], [DELIVERY_DATE] 236 | 237 | # Avoid - unclear abbreviations 238 | [CN], [ON], [DD] 239 | ``` 240 | 241 | ### 3. Document Your Prompts 242 | 243 | ```text 244 | # Description: What this prompt does 245 | # Tags: classification, tags 246 | # Version: 1.0 247 | # Author: Your Name 248 | # Last Updated: 2024-01-15 249 | 250 | //include common/disclaimer.txt 251 | 252 | Your prompt content... 253 | 254 | __END__ 255 | Internal notes, change history, and documentation go here. 256 | This section is ignored by the processor. 257 | ``` 258 | 259 | ### 4. Version Your Parameters 260 | 261 | ```json 262 | { 263 | "_meta": { 264 | "version": "1.0", 265 | "updated": "2024-01-15", 266 | "notes": "Added new product categories" 267 | }, 268 | "[CATEGORY]": ["electronics", "books", "clothing"] 269 | } 270 | ``` 271 | 272 | ## Advanced Concepts 273 | 274 | ### Parameter Validation 275 | 276 | ```ruby 277 | # Custom validation in your application 278 | def validate_parameters(prompt) 279 | required = prompt.keywords 280 | provided = prompt.parameters.keys 281 | missing = required - provided 282 | 283 | raise "Missing parameters: #{missing.join(', ')}" unless missing.empty? 284 | end 285 | ``` 286 | 287 | ### Dynamic Prompts 288 | 289 | ```text 290 | # Template selection based on parameters 291 | //include templates/[TEMPLATE_TYPE].txt 292 | 293 | # Conditional content using ERB 294 | <% if '[URGENCY]' == 'high' %> 295 | 🚨 URGENT: Immediate attention required 296 | <% end %> 297 | ``` 298 | 299 | ### Search Integration 300 | 301 | ```ruby 302 | # Configure custom search 303 | adapter.search_proc = ->(query) { 304 | # Use ripgrep for fast search 305 | `rg -l "#{query}" #{prompts_dir}`.split("\n").map { |f| 306 | File.basename(f, '.txt') 307 | } 308 | } 309 | ``` 310 | 311 | ## Next Steps 312 | 313 | Now that you understand the basics: 314 | 315 | 1. **Try the examples** in [Core Features](../core-features/parameterized-prompts.md) 316 | 2. **Choose a storage adapter** in [Storage Adapters](../storage/overview.md) 317 | 3. **Explore advanced features** in [Advanced Usage](../advanced/custom-keywords.md) 318 | 4. **See real applications** in [Examples](../examples/basic.md) -------------------------------------------------------------------------------- /docs/api/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration API Reference 2 | 3 | PromptManager provides comprehensive configuration options to customize behavior for your specific needs. 4 | 5 | ## Basic Configuration 6 | 7 | ```ruby 8 | PromptManager.configure do |config| 9 | # Storage adapter (default: FileSystemAdapter) 10 | config.storage = PromptManager::Storage::FileSystemAdapter.new 11 | 12 | # Default prompts directory (default: ~/prompts_dir/) 13 | config.prompts_dir = '/path/to/your/prompts' 14 | 15 | # Enable debug logging (default: false) 16 | config.debug = true 17 | 18 | # Custom logger (default: Rails.logger or Logger.new(STDOUT)) 19 | config.logger = Logger.new('/var/log/prompt_manager.log') 20 | end 21 | ``` 22 | 23 | ## Configuration Options 24 | 25 | ### Core Settings 26 | 27 | #### `storage` 28 | **Type:** `PromptManager::Storage::Base` 29 | **Default:** `FileSystemAdapter.new` 30 | 31 | The storage adapter to use for reading and writing prompts. 32 | 33 | ```ruby 34 | # FileSystem storage 35 | config.storage = PromptManager::Storage::FileSystemAdapter.new( 36 | prompts_dir: '/custom/prompts/path' 37 | ) 38 | 39 | # ActiveRecord storage 40 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new( 41 | model_class: Prompt 42 | ) 43 | 44 | # Custom storage 45 | config.storage = MyCustomAdapter.new 46 | ``` 47 | 48 | #### `prompts_dir` 49 | **Type:** `String` or `Array` 50 | **Default:** `File.join(Dir.home, 'prompts_dir')` 51 | 52 | Directory path(s) to search for prompt files when using FileSystemAdapter. 53 | 54 | ```ruby 55 | # Single directory 56 | config.prompts_dir = '/app/prompts' 57 | 58 | # Multiple directories (search in order) 59 | config.prompts_dir = [ 60 | '/app/prompts', 61 | '/shared/prompts', 62 | '/system/default_prompts' 63 | ] 64 | ``` 65 | 66 | #### `debug` 67 | **Type:** `Boolean` 68 | **Default:** `false` 69 | 70 | Enable debug logging for troubleshooting. 71 | 72 | ```ruby 73 | config.debug = true 74 | ``` 75 | 76 | #### `logger` 77 | **Type:** `Logger` 78 | **Default:** `Rails.logger` or `Logger.new(STDOUT)` 79 | 80 | Custom logger instance for PromptManager output. 81 | 82 | ```ruby 83 | config.logger = Logger.new('/var/log/prompt_manager.log') 84 | config.logger.level = Logger::DEBUG 85 | ``` 86 | 87 | ### Parameter Processing 88 | 89 | #### `save_parameter_history` 90 | **Type:** `Boolean` 91 | **Default:** `true` 92 | 93 | Whether to save parameter values for reuse in future prompt renderings. 94 | 95 | ```ruby 96 | config.save_parameter_history = false 97 | ``` 98 | 99 | #### `parameter_history_file` 100 | **Type:** `String` 101 | **Default:** `~/.prompt_manager/parameters_history.yaml` 102 | 103 | File path for storing parameter history. 104 | 105 | ```ruby 106 | config.parameter_history_file = '/app/data/prompt_history.yaml' 107 | ``` 108 | 109 | #### `max_history_entries` 110 | **Type:** `Integer` 111 | **Default:** `10` 112 | 113 | Maximum number of historical values to store per parameter. 114 | 115 | ```ruby 116 | config.max_history_entries = 5 117 | ``` 118 | 119 | ### ERB Processing 120 | 121 | #### `erb_timeout` 122 | **Type:** `Numeric` 123 | **Default:** `30` (seconds) 124 | 125 | Timeout for ERB template processing to prevent infinite loops. 126 | 127 | ```ruby 128 | config.erb_timeout = 60 # 1 minute 129 | ``` 130 | 131 | #### `erb_safe_level` 132 | **Type:** `Integer` 133 | **Default:** `0` 134 | 135 | Ruby safe level for ERB evaluation (0-4, higher = more restrictive). 136 | 137 | ```ruby 138 | config.erb_safe_level = 1 # Slightly more restrictive 139 | ``` 140 | 141 | ### Directive Processing 142 | 143 | #### `max_include_depth` 144 | **Type:** `Integer` 145 | **Default:** `10` 146 | 147 | Maximum depth for nested `//include` directives to prevent circular includes. 148 | 149 | ```ruby 150 | config.max_include_depth = 5 151 | ``` 152 | 153 | #### `directive_timeout` 154 | **Type:** `Numeric` 155 | **Default:** `30` (seconds) 156 | 157 | Timeout for directive processing. 158 | 159 | ```ruby 160 | config.directive_timeout = 60 161 | ``` 162 | 163 | ### Caching 164 | 165 | #### `cache_prompts` 166 | **Type:** `Boolean` 167 | **Default:** `false` 168 | 169 | Enable in-memory caching of prompt content. 170 | 171 | ```ruby 172 | config.cache_prompts = true 173 | ``` 174 | 175 | #### `cache_ttl` 176 | **Type:** `Numeric` 177 | **Default:** `300` (5 minutes) 178 | 179 | Time-to-live for cached prompt content in seconds. 180 | 181 | ```ruby 182 | config.cache_ttl = 600 # 10 minutes 183 | ``` 184 | 185 | #### `cache_store` 186 | **Type:** `ActiveSupport::Cache::Store` 187 | **Default:** `ActiveSupport::Cache::MemoryStore.new` 188 | 189 | Custom cache store for prompt content. 190 | 191 | ```ruby 192 | config.cache_store = ActiveSupport::Cache::RedisStore.new( 193 | url: ENV['REDIS_URL'] 194 | ) 195 | ``` 196 | 197 | ### Error Handling 198 | 199 | #### `error_handler` 200 | **Type:** `Proc` 201 | **Default:** `nil` 202 | 203 | Custom error handler for prompt processing errors. 204 | 205 | ```ruby 206 | config.error_handler = ->(error, context) { 207 | Rails.logger.error "Prompt error: #{error.message}" 208 | ErrorReporter.notify(error, context: context) 209 | 210 | # Return fallback content 211 | "Service temporarily unavailable" 212 | } 213 | ``` 214 | 215 | #### `raise_on_missing_prompts` 216 | **Type:** `Boolean` 217 | **Default:** `true` 218 | 219 | Whether to raise exceptions for missing prompts or return nil. 220 | 221 | ```ruby 222 | config.raise_on_missing_prompts = false 223 | ``` 224 | 225 | #### `raise_on_missing_parameters` 226 | **Type:** `Boolean` 227 | **Default:** `true` 228 | 229 | Whether to raise exceptions for missing parameters or substitute with placeholders. 230 | 231 | ```ruby 232 | config.raise_on_missing_parameters = false 233 | ``` 234 | 235 | ## Environment-based Configuration 236 | 237 | ### Rails Configuration 238 | 239 | ```ruby 240 | # config/environments/development.rb 241 | Rails.application.configure do 242 | config.prompt_manager.debug = true 243 | config.prompt_manager.prompts_dir = Rails.root.join('app', 'prompts') 244 | config.prompt_manager.save_parameter_history = true 245 | end 246 | 247 | # config/environments/production.rb 248 | Rails.application.configure do 249 | config.prompt_manager.debug = false 250 | config.prompt_manager.cache_prompts = true 251 | config.prompt_manager.cache_ttl = 3600 # 1 hour 252 | 253 | config.prompt_manager.error_handler = ->(error, context) { 254 | Rollbar.error(error, context) 255 | "Service temporarily unavailable" 256 | } 257 | end 258 | ``` 259 | 260 | ### Environment Variables 261 | 262 | PromptManager respects these environment variables: 263 | 264 | ```bash 265 | # Storage configuration 266 | PROMPT_MANAGER_PROMPTS_DIR="/app/prompts" 267 | PROMPT_MANAGER_DEBUG="true" 268 | 269 | # Cache configuration 270 | PROMPT_MANAGER_CACHE_PROMPTS="true" 271 | PROMPT_MANAGER_CACHE_TTL="600" 272 | 273 | # Database URL for ActiveRecord adapter 274 | DATABASE_URL="postgres://user:pass@localhost/prompts_db" 275 | ``` 276 | 277 | ## Configuration Validation 278 | 279 | Validate your configuration: 280 | 281 | ```ruby 282 | PromptManager.configure do |config| 283 | config.storage = MyAdapter.new 284 | config.debug = true 285 | end 286 | 287 | # Validate configuration 288 | begin 289 | PromptManager.validate_configuration! 290 | puts "Configuration valid" 291 | rescue PromptManager::ConfigurationError => e 292 | puts "Configuration error: #{e.message}" 293 | end 294 | ``` 295 | 296 | ## Runtime Configuration 297 | 298 | Access current configuration: 299 | 300 | ```ruby 301 | # Get current storage adapter 302 | storage = PromptManager.configuration.storage 303 | 304 | # Check debug mode 305 | if PromptManager.configuration.debug 306 | puts "Debug mode enabled" 307 | end 308 | 309 | # Access logger 310 | PromptManager.configuration.logger.info("Processing prompt...") 311 | ``` 312 | 313 | ## Configuration Best Practices 314 | 315 | ### Development 316 | ```ruby 317 | PromptManager.configure do |config| 318 | config.debug = true 319 | config.prompts_dir = './prompts' 320 | config.save_parameter_history = true 321 | config.cache_prompts = false # Always reload for development 322 | end 323 | ``` 324 | 325 | ### Production 326 | ```ruby 327 | PromptManager.configure do |config| 328 | config.debug = false 329 | config.cache_prompts = true 330 | config.cache_ttl = 3600 331 | 332 | config.error_handler = ->(error, context) { 333 | ErrorService.notify(error, context) 334 | "Service temporarily unavailable" 335 | } 336 | 337 | # Use database storage for high availability 338 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new 339 | end 340 | ``` 341 | 342 | ### Testing 343 | ```ruby 344 | # spec/spec_helper.rb 345 | RSpec.configure do |config| 346 | config.before(:each) do 347 | PromptManager.configure do |config| 348 | config.prompts_dir = Rails.root.join('spec', 'fixtures', 'prompts') 349 | config.save_parameter_history = false 350 | config.cache_prompts = false 351 | config.raise_on_missing_prompts = true 352 | end 353 | end 354 | end 355 | ``` -------------------------------------------------------------------------------- /docs/development/roadmap.md: -------------------------------------------------------------------------------- 1 | # Roadmap 2 | 3 | This roadmap outlines the planned features, improvements, and long-term direction for PromptManager. 4 | 5 | ## Current Version (0.5.x) 6 | 7 | ### Completed ✅ 8 | - Core prompt management functionality 9 | - FileSystem and ActiveRecord storage adapters 10 | - Parameter substitution with nested object support 11 | - ERB template integration 12 | - Basic directive processing (`//include`) 13 | - Environment variable substitution 14 | - Parameter history tracking 15 | - Comprehensive error handling 16 | - Documentation website 17 | 18 | ### In Progress 🚧 19 | - Performance optimization for large prompt libraries 20 | - Enhanced search and filtering capabilities 21 | - Improved error messages and debugging tools 22 | 23 | ## Version 1.0.0 - Stable Foundation (Q2 2024) 24 | 25 | ### Major Features 26 | - **Stable API**: Finalized public API with semantic versioning commitment 27 | - **Enhanced Storage Options**: 28 | - Redis adapter 29 | - S3/cloud storage adapter 30 | - Encrypted storage support 31 | - **Advanced Templating**: 32 | - Custom directive system 33 | - Template inheritance 34 | - Conditional rendering improvements 35 | - **Developer Experience**: 36 | - CLI tool for prompt management 37 | - VS Code extension for syntax highlighting 38 | - Interactive prompt editor 39 | 40 | ### Performance & Scalability 41 | - Lazy loading for large prompt libraries 42 | - Caching layer improvements 43 | - Bulk operations API 44 | - Memory usage optimization 45 | 46 | ### Quality Assurance 47 | - 95%+ test coverage 48 | - Performance benchmarking 49 | - Security audit 50 | - Documentation completeness review 51 | 52 | ## Version 1.1.0 - Collaboration Features (Q3 2024) 53 | 54 | ### Team Collaboration 55 | - **Version Control Integration**: 56 | - Git-based prompt versioning 57 | - Diff and merge capabilities for prompts 58 | - Branch-based development workflows 59 | - **Multi-user Support**: 60 | - User permissions and access control 61 | - Approval workflows for prompt changes 62 | - Audit logging for all operations 63 | 64 | ### Content Management 65 | - **Prompt Organization**: 66 | - Tags and categories 67 | - Collections and workspaces 68 | - Advanced search with faceted navigation 69 | - **Quality Control**: 70 | - Prompt linting and validation 71 | - A/B testing framework 72 | - Usage analytics and insights 73 | 74 | ## Version 1.2.0 - AI Integration (Q4 2024) 75 | 76 | ### AI-Powered Features 77 | - **Intelligent Prompt Assistance**: 78 | - AI-powered prompt generation 79 | - Optimization suggestions 80 | - Automatic parameter extraction 81 | - **Smart Search**: 82 | - Semantic search using embeddings 83 | - Similar prompt recommendations 84 | - Context-aware suggestions 85 | 86 | ### Integration Capabilities 87 | - **LLM Provider Integration**: 88 | - Direct integration with OpenAI, Anthropic, etc. 89 | - Prompt testing and validation 90 | - Response caching and optimization 91 | - **Workflow Automation**: 92 | - Automated prompt testing 93 | - Performance monitoring 94 | - Quality metrics tracking 95 | 96 | ## Version 2.0.0 - Enterprise Platform (Q2 2025) 97 | 98 | ### Enterprise Features 99 | - **Scalability**: 100 | - Multi-tenant architecture 101 | - Horizontal scaling support 102 | - Enterprise-grade security 103 | - **Integration Platform**: 104 | - REST API and GraphQL endpoints 105 | - Webhook system 106 | - Third-party integrations (Slack, Teams, etc.) 107 | 108 | ### Advanced Analytics 109 | - **Usage Intelligence**: 110 | - Prompt performance analytics 111 | - User behavior insights 112 | - ROI tracking and reporting 113 | - **Optimization Engine**: 114 | - Automatic prompt optimization 115 | - Performance regression detection 116 | - Resource usage optimization 117 | 118 | ### Governance & Compliance 119 | - **Security & Compliance**: 120 | - SOC 2 Type II compliance 121 | - GDPR/CCPA compliance tools 122 | - Data encryption at rest and in transit 123 | - **Governance**: 124 | - Policy management 125 | - Compliance reporting 126 | - Data retention controls 127 | 128 | ## Long-term Vision (2025+) 129 | 130 | ### Platform Evolution 131 | - **Microservices Architecture**: Break down into specialized services 132 | - **Event-Driven Architecture**: Real-time prompt updates and notifications 133 | - **Global CDN**: Distributed prompt delivery for low latency 134 | - **Multi-Language Support**: Native support for multiple programming languages 135 | 136 | ### AI/ML Advancements 137 | - **Prompt Evolution**: AI that learns and improves prompts over time 138 | - **Contextual Intelligence**: Automatic context injection based on usage patterns 139 | - **Predictive Analytics**: Forecast prompt performance and usage trends 140 | 141 | ### Developer Ecosystem 142 | - **Plugin System**: Extensible architecture for third-party plugins 143 | - **Marketplace**: Community-driven prompt and template sharing 144 | - **SDK Library**: Native SDKs for popular languages and frameworks 145 | 146 | ## Feature Requests & Community Input 147 | 148 | ### Highly Requested Features 149 | 1. **Visual Prompt Editor** - GUI for non-technical users 150 | 2. **Prompt Templates Gallery** - Pre-built templates for common use cases 151 | 3. **Integration Connectors** - Native connectors for popular tools 152 | 4. **Mobile App** - Mobile application for prompt management 153 | 5. **Backup/Export Tools** - Data portability and backup solutions 154 | 155 | ### Research & Exploration 156 | - **Prompt Compression**: Techniques to reduce prompt size while maintaining effectiveness 157 | - **Multi-Modal Prompts**: Support for image, audio, and video prompts 158 | - **Federated Learning**: Collaborative improvement without sharing sensitive data 159 | - **Quantum-Safe Encryption**: Future-proof security measures 160 | 161 | ## Release Schedule 162 | 163 | ### Release Cadence 164 | - **Major Releases**: Every 6-9 months 165 | - **Minor Releases**: Every 2-3 months 166 | - **Patch Releases**: As needed (security, critical bugs) 167 | - **Beta/RC Releases**: 2-4 weeks before major releases 168 | 169 | ### Version Support Policy 170 | - **Latest Major Version**: Full support (features, bugs, security) 171 | - **Previous Major Version**: Bug fixes and security updates for 18 months 172 | - **Legacy Versions**: Security updates only for 12 months after end of life 173 | 174 | ## Contributing to the Roadmap 175 | 176 | ### How to Influence the Roadmap 177 | 1. **Feature Requests**: Submit detailed feature requests via GitHub Issues 178 | 2. **Community Discussion**: Participate in roadmap discussions 179 | 3. **User Research**: Provide feedback through surveys and interviews 180 | 4. **Pull Requests**: Contribute implementations for planned features 181 | 182 | ### Prioritization Criteria 183 | - **User Impact**: How many users benefit and to what degree 184 | - **Strategic Alignment**: Fits with long-term vision and goals 185 | - **Technical Feasibility**: Implementation complexity and maintainability 186 | - **Community Support**: Level of community interest and contribution 187 | - **Business Value**: Commercial viability and sustainability 188 | 189 | ### Feedback Channels 190 | - **GitHub Discussions**: For feature ideas and architectural discussions 191 | - **User Surveys**: Quarterly surveys on feature priorities 192 | - **Community Calls**: Monthly calls with active contributors 193 | - **Beta Programs**: Early access to new features for feedback 194 | 195 | ## Migration & Compatibility 196 | 197 | ### Breaking Changes Policy 198 | - **Semantic Versioning**: Follow strict semantic versioning 199 | - **Deprecation Warnings**: 6-month warning period before removal 200 | - **Migration Guides**: Detailed guides for all breaking changes 201 | - **Automated Migration**: Tools to assist with major version upgrades 202 | 203 | ### Backward Compatibility 204 | - **API Stability**: Public API remains stable within major versions 205 | - **Configuration**: Configuration format maintained across minor versions 206 | - **Storage Format**: Storage adapters maintain backward compatibility 207 | - **Plugin Interface**: Plugin API versioning and compatibility matrix 208 | 209 | ## Success Metrics 210 | 211 | ### Technical Metrics 212 | - **Performance**: Sub-100ms prompt rendering for 95th percentile 213 | - **Reliability**: 99.9% uptime for cloud-hosted services 214 | - **Scalability**: Support for 1M+ prompts per instance 215 | - **Security**: Zero critical security vulnerabilities 216 | 217 | ### Adoption Metrics 218 | - **Community Growth**: 10,000+ GitHub stars by end of 2024 219 | - **Enterprise Adoption**: 100+ enterprise customers by 2025 220 | - **Ecosystem**: 50+ community-contributed plugins and integrations 221 | - **Documentation**: 95%+ documentation coverage for all features 222 | 223 | ### Quality Metrics 224 | - **Code Coverage**: Maintain 90%+ test coverage 225 | - **Documentation Score**: 4.5/5 average user rating 226 | - **Support Response**: <24 hour response time for critical issues 227 | - **Community Satisfaction**: 8/10 average satisfaction score 228 | 229 | --- 230 | 231 | *This roadmap is a living document that evolves based on user feedback, market conditions, and technical discoveries. While we strive to deliver on these plans, priorities may shift to better serve our community.* 232 | 233 | **Last Updated**: January 2024 234 | **Next Review**: April 2024 -------------------------------------------------------------------------------- /docs/storage/activerecord-adapter.md: -------------------------------------------------------------------------------- 1 | # ActiveRecordAdapter 2 | 3 | The ActiveRecordAdapter allows you to store prompts in a relational database using ActiveRecord, perfect for Rails applications and scenarios requiring database-backed prompt storage. 4 | 5 | ## Overview 6 | 7 | Store prompts in your application's database alongside other application data. This adapter provides full CRUD operations, query capabilities, and integration with ActiveRecord models. 8 | 9 | ## Setup 10 | 11 | ### Migration 12 | 13 | Create the prompts table: 14 | 15 | ```ruby 16 | # Generate migration 17 | rails generate migration CreatePrompts 18 | 19 | # In the migration file: 20 | class CreatePrompts < ActiveRecord::Migration[7.0] 21 | def change 22 | create_table :prompts do |t| 23 | t.string :prompt_id, null: false, index: { unique: true } 24 | t.text :content, null: false 25 | t.text :description 26 | t.json :metadata, default: {} 27 | t.timestamps 28 | end 29 | end 30 | end 31 | ``` 32 | 33 | ### Model 34 | 35 | ```ruby 36 | # app/models/prompt.rb 37 | class Prompt < ApplicationRecord 38 | validates :prompt_id, presence: true, uniqueness: true 39 | validates :content, presence: true 40 | 41 | # Optional: Add scopes for organization 42 | scope :by_category, ->(category) { where("metadata->>'category' = ?", category) } 43 | scope :recent, -> { order(updated_at: :desc) } 44 | end 45 | ``` 46 | 47 | ### Configuration 48 | 49 | ```ruby 50 | # Configure PromptManager to use ActiveRecord 51 | PromptManager.configure do |config| 52 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new( 53 | model_class: Prompt, 54 | id_column: :prompt_id, 55 | content_column: :content 56 | ) 57 | end 58 | ``` 59 | 60 | ## Basic Usage 61 | 62 | ### Creating Prompts 63 | 64 | ```ruby 65 | # Create via PromptManager 66 | prompt = PromptManager::Prompt.new(id: 'welcome_email') 67 | prompt.save( 68 | content: 'Welcome to our service, [USER_NAME]!', 69 | metadata: { 70 | category: 'email', 71 | author: 'marketing_team', 72 | version: '1.0' 73 | } 74 | ) 75 | 76 | # Or create via ActiveRecord 77 | Prompt.create!( 78 | prompt_id: 'goodbye_email', 79 | content: 'Thanks for using our service, [USER_NAME]!', 80 | description: 'Farewell email template', 81 | metadata: { category: 'email', priority: 'low' } 82 | ) 83 | ``` 84 | 85 | ### Reading Prompts 86 | 87 | ```ruby 88 | # Via PromptManager (recommended) 89 | prompt = PromptManager::Prompt.new(id: 'welcome_email') 90 | result = prompt.render(user_name: 'Alice') 91 | 92 | # Via ActiveRecord 93 | prompt_record = Prompt.find_by(prompt_id: 'welcome_email') 94 | puts prompt_record.content 95 | ``` 96 | 97 | ### Updating Prompts 98 | 99 | ```ruby 100 | # Via PromptManager 101 | prompt = PromptManager::Prompt.new(id: 'welcome_email') 102 | prompt.save('Updated content: Welcome [USER_NAME] to our platform!') 103 | 104 | # Via ActiveRecord 105 | prompt_record = Prompt.find_by(prompt_id: 'welcome_email') 106 | prompt_record.update!( 107 | content: 'Updated content...', 108 | metadata: prompt_record.metadata.merge(version: '1.1') 109 | ) 110 | ``` 111 | 112 | ## Advanced Features 113 | 114 | ### Query Interface 115 | 116 | ```ruby 117 | # Configure with query support 118 | PromptManager.configure do |config| 119 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new( 120 | model_class: Prompt, 121 | id_column: :prompt_id, 122 | content_column: :content, 123 | enable_queries: true 124 | ) 125 | end 126 | 127 | # Search prompts 128 | results = PromptManager.storage.search( 129 | category: 'email', 130 | content_contains: 'welcome' 131 | ) 132 | 133 | # List by metadata 134 | email_prompts = PromptManager.storage.where( 135 | "metadata->>'category' = ?", 'email' 136 | ) 137 | ``` 138 | 139 | ### Versioning 140 | 141 | ```ruby 142 | # Add versioning to your model 143 | class Prompt < ApplicationRecord 144 | has_many :prompt_versions, dependent: :destroy 145 | 146 | before_update :create_version 147 | 148 | private 149 | 150 | def create_version 151 | if content_changed? 152 | prompt_versions.create!( 153 | content: content_was, 154 | version_number: (prompt_versions.maximum(:version_number) || 0) + 1, 155 | created_at: updated_at_was 156 | ) 157 | end 158 | end 159 | end 160 | 161 | # Version model 162 | class PromptVersion < ApplicationRecord 163 | belongs_to :prompt 164 | end 165 | 166 | # Migration for versions 167 | class CreatePromptVersions < ActiveRecord::Migration[7.0] 168 | def change 169 | create_table :prompt_versions do |t| 170 | t.references :prompt, null: false, foreign_key: true 171 | t.text :content, null: false 172 | t.integer :version_number, null: false 173 | t.timestamps 174 | end 175 | 176 | add_index :prompt_versions, [:prompt_id, :version_number], unique: true 177 | end 178 | end 179 | ``` 180 | 181 | ### Multi-tenancy 182 | 183 | ```ruby 184 | # Add tenant support 185 | class Prompt < ApplicationRecord 186 | belongs_to :tenant 187 | 188 | validates :prompt_id, uniqueness: { scope: :tenant_id } 189 | 190 | scope :for_tenant, ->(tenant) { where(tenant: tenant) } 191 | end 192 | 193 | # Configure with tenant scope 194 | PromptManager.configure do |config| 195 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new( 196 | model_class: Prompt, 197 | id_column: :prompt_id, 198 | content_column: :content, 199 | scope: -> { Prompt.for_tenant(Current.tenant) } 200 | ) 201 | end 202 | ``` 203 | 204 | ## Performance Optimization 205 | 206 | ### Indexing 207 | 208 | ```ruby 209 | # Add performance indexes 210 | class AddPromptIndexes < ActiveRecord::Migration[7.0] 211 | def change 212 | add_index :prompts, :prompt_id, unique: true 213 | add_index :prompts, :updated_at 214 | add_index :prompts, "((metadata->>'category'))", name: 'index_prompts_on_category' 215 | add_index :prompts, :content, type: :gin # For full-text search (PostgreSQL) 216 | end 217 | end 218 | ``` 219 | 220 | ### Caching 221 | 222 | ```ruby 223 | # Configure caching 224 | PromptManager.configure do |config| 225 | config.storage = PromptManager::Storage::ActiveRecordAdapter.new( 226 | model_class: Prompt, 227 | id_column: :prompt_id, 228 | content_column: :content, 229 | cache_queries: true, 230 | cache_ttl: 300 # 5 minutes 231 | ) 232 | end 233 | 234 | # Add caching to your model 235 | class Prompt < ApplicationRecord 236 | after_update :clear_cache 237 | after_destroy :clear_cache 238 | 239 | private 240 | 241 | def clear_cache 242 | Rails.cache.delete("prompt:#{prompt_id}") 243 | end 244 | end 245 | ``` 246 | 247 | ### Connection Pooling 248 | 249 | ```ruby 250 | # For high-traffic applications 251 | class PromptReadOnlyRecord < ApplicationRecord 252 | self.abstract_class = true 253 | connects_to database: { reading: :prompt_replica } 254 | end 255 | 256 | class Prompt < PromptReadOnlyRecord 257 | # Read operations use replica database 258 | end 259 | ``` 260 | 261 | ## Integration Examples 262 | 263 | ### Rails Controller 264 | 265 | ```ruby 266 | class PromptsController < ApplicationController 267 | def show 268 | prompt = PromptManager::Prompt.new(id: params[:id]) 269 | @content = prompt.render(params.permit(:user_name, :product_name)) 270 | rescue PromptManager::PromptNotFoundError 271 | render json: { error: 'Prompt not found' }, status: 404 272 | end 273 | 274 | def create 275 | prompt = PromptManager::Prompt.new(id: prompt_params[:id]) 276 | prompt.save(prompt_params[:content]) 277 | 278 | render json: { message: 'Prompt created successfully' } 279 | rescue => e 280 | render json: { error: e.message }, status: 422 281 | end 282 | 283 | private 284 | 285 | def prompt_params 286 | params.require(:prompt).permit(:id, :content, :description, metadata: {}) 287 | end 288 | end 289 | ``` 290 | 291 | ### Background Jobs 292 | 293 | ```ruby 294 | class ProcessPromptJob < ApplicationJob 295 | def perform(prompt_id, parameters) 296 | prompt = PromptManager::Prompt.new(id: prompt_id) 297 | result = prompt.render(parameters) 298 | 299 | # Process the result 300 | NotificationService.send_message(result) 301 | rescue PromptManager::PromptNotFoundError => e 302 | logger.error "Prompt not found: #{prompt_id}" 303 | # Handle gracefully 304 | end 305 | end 306 | 307 | # Usage 308 | ProcessPromptJob.perform_later('daily_report', user_id: user.id) 309 | ``` 310 | 311 | ## Best Practices 312 | 313 | 1. **Use Transactions**: Wrap prompt operations in database transactions 314 | 2. **Validate Content**: Add model validations for prompt content 315 | 3. **Index Strategically**: Index frequently queried fields 316 | 4. **Cache Wisely**: Cache frequently accessed prompts 317 | 5. **Monitor Performance**: Track database query performance 318 | 6. **Backup Regularly**: Include prompts in your database backup strategy 319 | 7. **Version Control**: Consider versioning for important prompts 320 | 8. **Secure Access**: Use database-level permissions and encryption 321 | 322 | ## Migration from FileSystem 323 | 324 | ```ruby 325 | # Migrate from filesystem to database 326 | class MigratePromptsToDatabase 327 | def self.perform(prompts_dir) 328 | Dir.glob(File.join(prompts_dir, '**/*.txt')).each do |file_path| 329 | relative_path = Pathname.new(file_path).relative_path_from(Pathname.new(prompts_dir)) 330 | prompt_id = relative_path.sub_ext('').to_s 331 | content = File.read(file_path) 332 | 333 | Prompt.create!( 334 | prompt_id: prompt_id, 335 | content: content, 336 | description: "Migrated from #{file_path}", 337 | metadata: { 338 | original_file: file_path, 339 | migrated_at: Time.current 340 | } 341 | ) 342 | end 343 | end 344 | end 345 | 346 | # Run migration 347 | MigratePromptsToDatabase.perform('/path/to/prompts') 348 | ``` -------------------------------------------------------------------------------- /docs/examples.md: -------------------------------------------------------------------------------- 1 | # Examples 2 | 3 | This section provides comprehensive examples demonstrating various features and use cases of PromptManager. 4 | 5 | ## Basic Usage 6 | 7 | The simplest way to get started with PromptManager: 8 | 9 | ```ruby 10 | # examples/simple.rb 11 | require 'prompt_manager' 12 | 13 | # Configure storage adapter 14 | PromptManager::Prompt.storage_adapter = 15 | PromptManager::Storage::FileSystemAdapter.config do |config| 16 | config.prompts_dir = '~/.prompts' 17 | end.new 18 | 19 | # Create and use a prompt 20 | prompt = PromptManager::Prompt.new(id: 'greeting') 21 | prompt.parameters = { 22 | "[NAME]" => "Alice", 23 | "[LANGUAGE]" => "English" 24 | } 25 | 26 | # Get the processed prompt text 27 | puts prompt.to_s 28 | ``` 29 | 30 | ## Advanced Integration with LLM and Streaming 31 | 32 | The [advanced_integrations.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/advanced_integrations.rb) example demonstrates a complete integration with OpenAI's API, showcasing: 33 | 34 | ### Features Demonstrated 35 | 36 | - **ERB templating** for dynamic content generation 37 | - **Shell integration** for environment variable substitution 38 | - **OpenAI API integration** with streaming responses 39 | - **Professional UI** with spinner feedback using `tty-spinner` 40 | - **Real-time streaming** of LLM responses 41 | 42 | ### Code Overview 43 | 44 | ```ruby 45 | #!/usr/bin/env ruby 46 | # frozen_string_literal: true 47 | 48 | require 'bundler/inline' 49 | 50 | gemfile do 51 | source 'https://rubygems.org' 52 | gem 'prompt_manager' 53 | gem 'ruby-openai' 54 | gem 'tty-spinner' 55 | end 56 | 57 | require 'prompt_manager' 58 | require 'openai' 59 | require 'erb' 60 | require 'time' 61 | require 'tty-spinner' 62 | 63 | # Configure PromptManager with filesystem adapter 64 | PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.config do |config| 65 | config.prompts_dir = File.join(__dir__, 'prompts_dir') 66 | end.new 67 | 68 | # Configure OpenAI client 69 | client = OpenAI::Client.new( 70 | access_token: ENV['OPENAI_API_KEY'] 71 | ) 72 | 73 | # Get prompt instance with advanced features enabled 74 | prompt = PromptManager::Prompt.new( 75 | id: 'advanced_demo', 76 | erb_flag: true, # Enable ERB templating 77 | envar_flag: true # Enable environment variable substitution 78 | ) 79 | 80 | # Show spinner while waiting for response 81 | spinner = TTY::Spinner.new("[:spinner] Waiting for response...") 82 | spinner.auto_spin 83 | 84 | # Stream the response from OpenAI 85 | response = client.chat( 86 | parameters: { 87 | model: 'gpt-4o-mini', 88 | messages: [{ role: 'user', content: prompt.to_s }], 89 | stream: proc do |chunk, _bytesize| 90 | spinner.stop 91 | content = chunk.dig("choices", 0, "delta", "content") 92 | print content if content 93 | $stdout.flush 94 | end 95 | } 96 | ) 97 | 98 | puts 99 | ``` 100 | 101 | ### Prompt Template 102 | 103 | The example uses a sophisticated prompt template ([advanced_demo.txt](https://github.com/MadBomber/prompt_manager/blob/main/examples/prompts_dir/advanced_demo.txt)) that demonstrates: 104 | 105 | ```text 106 | # System Analysis and Historical Comparison Report 107 | # Generated with PromptManager - ERB + Shell Integration Demo 108 | 109 | ```markdown 110 | ## Current System Information 111 | 112 | **Timestamp**: <%= Time.now.strftime('%A, %B %d, %Y at %I:%M:%S %p %Z') %> 113 | **Analysis Duration**: <%= Time.now - Time.parse('2024-01-01') %> seconds since 2024 began 114 | 115 | ### Hardware Platform Details 116 | **Architecture**: $HOSTTYPE$MACHTYPE 117 | **Hostname**: $HOSTNAME 118 | **Operating System**: $OSTYPE 119 | **Shell**: $SHELL (version: $BASH_VERSION) 120 | **User**: $USER 121 | **Home Directory**: $HOME 122 | **Current Path**: $PWD 123 | **Terminal**: $TERM 124 | 125 | ### Detailed System Profile 126 | <% if RUBY_PLATFORM.include?('darwin') %> 127 | **Platform**: macOS/Darwin System 128 | **Ruby Platform**: <%= RUBY_PLATFORM %> 129 | **Ruby Version**: <%= RUBY_VERSION %> 130 | **Ruby Engine**: <%= RUBY_ENGINE %> 131 | <% elsif RUBY_PLATFORM.include?('linux') %> 132 | **Platform**: Linux System 133 | **Ruby Platform**: <%= RUBY_PLATFORM %> 134 | **Ruby Version**: <%= RUBY_VERSION %> 135 | **Ruby Engine**: <%= RUBY_ENGINE %> 136 | <% else %> 137 | **Platform**: Other Unix-like System 138 | **Ruby Platform**: <%= RUBY_PLATFORM %> 139 | **Ruby Version**: <%= RUBY_VERSION %> 140 | **Ruby Engine**: <%= RUBY_ENGINE %> 141 | <% end %> 142 | 143 | ### Performance Context 144 | **Load Average**: <%= `uptime`.strip rescue 'Unable to determine' %> 145 | **Memory Info**: <%= `vm_stat | head -5`.strip rescue 'Unable to determine' if RUBY_PLATFORM.include?('darwin') %> 146 | **Disk Usage**: <%= `df -h / | tail -1`.strip rescue 'Unable to determine' %> 147 | 148 | ## Analysis Request 149 | 150 | You are a technology historian and systems analyst. Please provide a comprehensive comparison between this current system and **the most powerful Apple computer created in the 20th century** (which would be from the 1990s). 151 | ``` 152 | 153 | ### Key Benefits 154 | 155 | 1. **Dynamic Content**: ERB templating allows for real-time system information gathering 156 | 2. **Environment Awareness**: Shell integration provides current system context 157 | 3. **Professional UX**: Spinner provides visual feedback during API calls 158 | 4. **Real-time Streaming**: Users see responses as they're generated 159 | 5. **Comprehensive Analysis**: The prompt generates detailed technical comparisons 160 | 161 | ## Search Integration 162 | 163 | See [using_search_proc.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/using_search_proc.rb) for advanced search capabilities: 164 | 165 | ```ruby 166 | # Configure custom search with ripgrep 167 | PromptManager::Storage::FileSystemAdapter.config do |config| 168 | config.prompts_dir = '~/.prompts' 169 | config.search_proc = ->(query) { 170 | # Use ripgrep for fast searching 171 | `rg -l "#{query}" #{config.prompts_dir}`.split("\n") 172 | .map { |path| File.basename(path, '.txt') } 173 | } 174 | end.new 175 | 176 | # Search for prompts containing specific terms 177 | results = PromptManager::Prompt.search("database queries") 178 | puts "Found prompts: #{results.join(', ')}" 179 | ``` 180 | 181 | ## Parameter Management 182 | 183 | ### Basic Parameters 184 | 185 | ```ruby 186 | prompt = PromptManager::Prompt.new(id: 'template') 187 | prompt.parameters = { 188 | "[NAME]" => "John", 189 | "[ROLE]" => "developer", 190 | "[PROJECT]" => "web application" 191 | } 192 | ``` 193 | 194 | ### Parameter History 195 | 196 | ```ruby 197 | # Parameters support history tracking 198 | prompt.parameters = { 199 | "[NAME]" => ["Alice", "Bob", "Charlie"] # Charlie is most recent 200 | } 201 | 202 | # Access current value 203 | current_name = prompt.parameters["[NAME]"].last 204 | 205 | # Access history 206 | name_history = prompt.parameters["[NAME]"] 207 | ``` 208 | 209 | ## Custom Storage Adapters 210 | 211 | ### Redis Storage Example 212 | 213 | ```ruby 214 | require 'redis' 215 | require 'json' 216 | 217 | class RedisAdapter 218 | def initialize(redis_client) 219 | @redis = redis_client 220 | end 221 | 222 | def get(id:) 223 | { 224 | id: id, 225 | text: @redis.get("prompt:#{id}:text") || "", 226 | parameters: JSON.parse(@redis.get("prompt:#{id}:params") || '{}') 227 | } 228 | end 229 | 230 | def save(id:, text:, parameters:) 231 | @redis.set("prompt:#{id}:text", text) 232 | @redis.set("prompt:#{id}:params", parameters.to_json) 233 | end 234 | 235 | def delete(id:) 236 | @redis.del("prompt:#{id}:text", "prompt:#{id}:params") 237 | end 238 | 239 | def search(query) 240 | # Simple search implementation 241 | @redis.keys("prompt:*:text").select do |key| 242 | content = @redis.get(key) 243 | content&.include?(query) 244 | end.map { |key| key.split(':')[1] } 245 | end 246 | 247 | def list 248 | @redis.keys("prompt:*:text").map { |key| key.split(':')[1] } 249 | end 250 | end 251 | 252 | # Usage 253 | redis = Redis.new 254 | PromptManager::Prompt.storage_adapter = RedisAdapter.new(redis) 255 | ``` 256 | 257 | ## Directive Processing 258 | 259 | ### Custom Directives 260 | 261 | ```ruby 262 | class CustomDirectiveProcessor < PromptManager::DirectiveProcessor 263 | def process_directive(directive, prompt) 264 | case directive 265 | when /^\/\/model (.+)$/ 266 | set_model($1) 267 | when /^\/\/temperature (.+)$/ 268 | set_temperature($1.to_f) 269 | when /^\/\/max_tokens (\d+)$/ 270 | set_max_tokens($1.to_i) 271 | else 272 | super # Handle built-in directives 273 | end 274 | end 275 | 276 | private 277 | 278 | def set_model(model) 279 | @model = model 280 | end 281 | 282 | def set_temperature(temp) 283 | @temperature = temp 284 | end 285 | 286 | def set_max_tokens(tokens) 287 | @max_tokens = tokens 288 | end 289 | end 290 | 291 | # Usage 292 | prompt = PromptManager::Prompt.new( 293 | id: 'ai_prompt', 294 | directives_processor: CustomDirectiveProcessor.new 295 | ) 296 | ``` 297 | 298 | ## Error Handling 299 | 300 | ```ruby 301 | begin 302 | prompt = PromptManager::Prompt.new(id: 'nonexistent') 303 | result = prompt.to_s 304 | rescue PromptManager::StorageError => e 305 | puts "Storage error: #{e.message}" 306 | rescue PromptManager::ParameterError => e 307 | puts "Parameter error: #{e.message}" 308 | rescue PromptManager::ConfigurationError => e 309 | puts "Configuration error: #{e.message}" 310 | end 311 | ``` 312 | 313 | ## Testing Integration 314 | 315 | ```ruby 316 | # Test helper for prompt testing 317 | def test_prompt(id, params = {}) 318 | prompt = PromptManager::Prompt.new(id: id) 319 | prompt.parameters = params 320 | prompt.to_s 321 | end 322 | 323 | # Example test 324 | describe "greeting prompt" do 325 | it "personalizes the greeting" do 326 | result = test_prompt('greeting', { 327 | "[NAME]" => "Alice", 328 | "[TIME]" => "morning" 329 | }) 330 | 331 | expect(result).to include("Hello Alice") 332 | expect(result).to include("Good morning") 333 | end 334 | end 335 | ``` 336 | 337 | For more examples and advanced usage patterns, see the complete examples in the [examples/](https://github.com/MadBomber/prompt_manager/tree/main/examples) directory. -------------------------------------------------------------------------------- /COMMITS.md: -------------------------------------------------------------------------------- 1 | --- 2 | url: https://www.conventionalcommits.org/en/v1.0.0/ 3 | title: Conventional Commits 4 | description: A specification for adding human and machine readable meaning to commit messages 5 | access_date: 2025-07-31T20:51:29.000Z 6 | current_date: 2025-07-31T20:51:29.601Z 7 | --- 8 | 9 | # Conventional Commits 10 | 11 | A specification for adding human and machine readable meaning to commit messages 12 | 13 | Quick Summary Full Specification Contribute 14 | 15 | # Conventional Commits 1.0.0 16 | 17 | ## Summary 18 | 19 | The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages. 20 | 21 | The commit message should be structured as follows: 22 | 23 | --- 24 | 25 | ``` 26 | [optional scope]: 27 | 28 | [optional body] 29 | 30 | [optional footer(s)] 31 | 32 | ``` 33 | 34 | --- 35 | 36 | The commit contains the following structural elements, to communicate intent to the consumers of your library: 37 | 38 | 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with `PATCH` in Semantic Versioning). 39 | 2. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with `MINOR` in Semantic Versioning). 40 | 3. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any _type_. 41 | 4. _types_ other than `fix:` and `feat:` are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends `build:`, `chore:`,`ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. 42 | 5. _footers_ other than `BREAKING CHANGE: ` may be provided and follow a convention similar to git trailer format. 43 | 44 | Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`. 45 | 46 | ## Examples 47 | 48 | ### Commit message with description and breaking change footer 49 | 50 | ``` 51 | feat: allow provided config object to extend other configs 52 | 53 | BREAKING CHANGE: `extends` key in config file is now used for extending other config files 54 | 55 | ``` 56 | 57 | ### Commit message with `!` to draw attention to breaking change 58 | 59 | ``` 60 | feat!: send an email to the customer when a product is shipped 61 | 62 | ``` 63 | 64 | ### Commit message with scope and `!` to draw attention to breaking change 65 | 66 | ``` 67 | feat(api)!: send an email to the customer when a product is shipped 68 | 69 | ``` 70 | 71 | ### Commit message with both `!` and BREAKING CHANGE footer 72 | 73 | ``` 74 | chore!: drop support for Node 6 75 | 76 | BREAKING CHANGE: use JavaScript features not available in Node 6. 77 | 78 | ``` 79 | 80 | ### Commit message with no body 81 | 82 | ``` 83 | docs: correct spelling of CHANGELOG 84 | 85 | ``` 86 | 87 | ### Commit message with scope 88 | 89 | ``` 90 | feat(lang): add Polish language 91 | 92 | ``` 93 | 94 | ### Commit message with multi-paragraph body and multiple footers 95 | 96 | ``` 97 | fix: prevent racing of requests 98 | 99 | Introduce a request id and a reference to latest request. Dismiss 100 | incoming responses other than from latest request. 101 | 102 | Remove timeouts which were used to mitigate the racing issue but are 103 | obsolete now. 104 | 105 | Reviewed-by: Z 106 | Refs: #123 107 | 108 | ``` 109 | 110 | ## Specification 111 | 112 | The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. 113 | 114 | 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal colon and space. 115 | 2. The type `feat` MUST be used when a commit adds a new feature to your application or library. 116 | 3. The type `fix` MUST be used when a commit represents a bug fix for your application. 117 | 4. A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., `fix(parser):` 118 | 5. A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_. 119 | 6. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 120 | 7. A commit body is free-form and MAY consist of any number of newline separated paragraphs. 121 | 8. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a `:` or `#` separator, followed by a string value (this is inspired by the git trailer convention). 122 | 9. A footer’s token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token. 123 | 10. A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. 124 | 11. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. 125 | 12. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g.,_BREAKING CHANGE: environment variables now take precedence over config files_. 126 | 13. If included in the type/scope prefix, breaking changes MUST be indicated by a`!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change. 127 | 14. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: update ref docs._ 128 | 15. The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. 129 | 16. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer. 130 | 131 | ## Why Use Conventional Commits 132 | 133 | * Automatically generating CHANGELOGs. 134 | * Automatically determining a semantic version bump (based on the types of commits landed). 135 | * Communicating the nature of changes to teammates, the public, and other stakeholders. 136 | * Triggering build and publish processes. 137 | * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. 138 | 139 | ## FAQ 140 | 141 | ### How should I deal with commit messages in the initial development phase? 142 | 143 | We recommend that you proceed as if you’ve already released the product. Typically _somebody_, even if it’s your fellow software developers, is using your software. They’ll want to know what’s fixed, what breaks etc. 144 | 145 | ### Are the types in the commit title uppercase or lowercase? 146 | 147 | Any casing may be used, but it’s best to be consistent. 148 | 149 | ### What do I do if the commit conforms to more than one of the commit types? 150 | 151 | Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. 152 | 153 | ### Doesn’t this discourage rapid development and fast iteration? 154 | 155 | It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. 156 | 157 | ### Might Conventional Commits lead developers to limit the type of commits they make because they’ll be thinking in the types provided? 158 | 159 | Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. 160 | 161 | ### How does this relate to SemVer? 162 | 163 | `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. 164 | 165 | ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? 166 | 167 | We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) 168 | 169 | ### What do I do if I accidentally use the wrong commit type? 170 | 171 | #### When you used a type that’s of the spec but not the correct type, e.g. `fix` instead of `feat` 172 | 173 | Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. 174 | 175 | #### When you used a type _not_ of the spec, e.g. `feet` instead of `feat` 176 | 177 | In a worst case scenario, it’s not the end of the world if a commit lands that does not meet the Conventional Commits specification. It simply means that commit will be missed by tools that are based on the spec. 178 | 179 | ### Do all my contributors need to use the Conventional Commits specification? 180 | 181 | No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they’re merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. 182 | 183 | ### How does Conventional Commits handle revert commits? 184 | 185 | Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch? 186 | 187 | Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling authors to use the flexibility of _types_ and _footers_ to develop their logic for handling reverts. 188 | 189 | One recommendation is to use the `revert` type, and a footer that references the commit SHAs that are being reverted: 190 | 191 | ``` 192 | revert: let us never again speak of the noodle incident 193 | 194 | Refs: 676104e, a215868 195 | 196 | ``` 197 | -------------------------------------------------------------------------------- /lib/prompt_manager/storage/file_system_adapter.rb: -------------------------------------------------------------------------------- 1 | # prompt_manager/lib/prompt_manager/storage/file_system_adapter.rb 2 | 3 | # Use the local (or remote) file system as a place to 4 | # store and access prompts. 5 | # 6 | # Adds two additional methods to the Prompt class: 7 | # list - returns Array of prompt IDs 8 | # path - returns a Pathname object to the prompt's text file 9 | # path(prompt_id) - same as path on the prompt instance 10 | # 11 | # Allows sub-directories of the prompts_dir to be 12 | # used like categories. For example the prompt_id "toy/magic" 13 | # is found in the `magic.txt` file inside the `toy` sub-directory 14 | # of the prompts_dir. 15 | # 16 | # There can be many layers of categories (sub-directories) 17 | # 18 | # This adapter serves as the file-based storage backend for PromptManager::Prompt, 19 | # enabling prompt retrieval and persistence using file system operations. 20 | 21 | require 'json' # basic serialization of parameters 22 | require 'pathname' 23 | require 'fileutils' 24 | 25 | class PromptManager::Storage::FileSystemAdapter 26 | # Placeholder for search proc 27 | SEARCH_PROC = nil 28 | # File extension for parameters 29 | PARAMS_EXTENSION = '.json'.freeze 30 | # File extension for prompts 31 | PROMPT_EXTENSION = '.txt'.freeze 32 | # Regular expression for valid prompt IDs 33 | PROMPT_ID_FORMAT = /^[a-zA-Z0-9\-\/_]+$/ 34 | 35 | class << self 36 | # Accessors for configuration options 37 | attr_accessor :prompts_dir, :search_proc, 38 | :params_extension, :prompt_extension 39 | 40 | # Configure the adapter 41 | def config 42 | if block_given? 43 | yield self 44 | validate_configuration 45 | else 46 | raise ArgumentError, "No block given to config" 47 | end 48 | 49 | self 50 | end 51 | 52 | # Expansion methods on the Prompt class specific to 53 | # this storage adapter. 54 | 55 | # Ignore the incoming prompt_id 56 | def list(prompt_id = nil) 57 | new.list 58 | end 59 | 60 | def path(prompt_id) 61 | new.path(prompt_id) 62 | end 63 | 64 | ################################################# 65 | private 66 | 67 | # Validate the configuration 68 | def validate_configuration 69 | validate_prompts_dir 70 | validate_search_proc 71 | validate_prompt_extension 72 | validate_params_extension 73 | end 74 | 75 | # Validate the prompts directory 76 | def validate_prompts_dir 77 | # This is a work around for a Ruby scope issue where the 78 | # class getter/setter method is becoming confused with a 79 | # local variable when anything other than plain 'ol get and 80 | # set are used. This error is in both Ruby v3.2.2 and 81 | # v3.3.0-preview3. 82 | # 83 | prompts_dir_local = self.prompts_dir 84 | 85 | raise ArgumentError, "prompts_dir must be set" if prompts_dir_local.nil? || prompts_dir_local.to_s.strip.empty? 86 | 87 | unless prompts_dir_local.is_a?(Pathname) 88 | prompts_dir_local = Pathname.new(prompts_dir_local) 89 | end 90 | 91 | prompts_dir_local = prompts_dir_local.expand_path 92 | 93 | unless prompts_dir_local.exist? 94 | FileUtils.mkdir_p(prompts_dir_local) 95 | end 96 | raise(ArgumentError, "prompts_dir: #{prompts_dir_local} is not a directory") unless prompts_dir_local.directory? 97 | 98 | self.prompts_dir = prompts_dir_local 99 | end 100 | 101 | # Validate the search proc 102 | def validate_search_proc 103 | search_proc_local = self.search_proc 104 | 105 | if search_proc_local.nil? 106 | search_proc_local = SEARCH_PROC 107 | else 108 | raise(ArgumentError, "search_proc invalid; does not respond to call") unless search_proc_local.respond_to?(:call) 109 | end 110 | 111 | self.search_proc = search_proc_local 112 | end 113 | 114 | # Validate the prompt extension 115 | def validate_prompt_extension 116 | prompt_extension_local = self.prompt_extension 117 | 118 | if prompt_extension_local.nil? 119 | prompt_extension_local = PROMPT_EXTENSION 120 | else 121 | unless prompt_extension_local.is_a?(String) && 122 | prompt_extension_local.start_with?('.') 123 | raise(ArgumentError, "Invalid prompt_extension: #{prompt_extension_local}") 124 | end 125 | end 126 | 127 | self.prompt_extension = prompt_extension_local 128 | end 129 | 130 | # Validate the params extension 131 | def validate_params_extension 132 | params_extension_local = self.params_extension 133 | 134 | if params_extension_local.nil? 135 | params_extension_local = PARAMS_EXTENSION 136 | else 137 | unless params_extension_local.is_a?(String) && 138 | params_extension_local.start_with?('.') 139 | raise(ArgumentError, "Invalid params_extension: #{params_extension_local}") 140 | end 141 | end 142 | 143 | self.params_extension = params_extension_local 144 | end 145 | end 146 | 147 | ################################################## 148 | ### 149 | ## Instance 150 | # 151 | 152 | # Accessors for instance variables 153 | def prompts_dir = self.class.prompts_dir 154 | def search_proc = self.class.search_proc 155 | def prompt_extension = self.class.prompt_extension 156 | def params_extension = self.class.params_extension 157 | 158 | # Initialize the adapter 159 | def initialize 160 | # NOTE: validate because main program may have made 161 | # changes outside of the config block 162 | self.class.send(:validate_configuration) # send gets around private designations of a method 163 | end 164 | 165 | # Get a prompt by ID 166 | def get(id:) 167 | validate_id(id) 168 | verify_id(id) 169 | 170 | { 171 | id: id, 172 | text: prompt_text(id), 173 | parameters: parameter_values(id) 174 | } 175 | end 176 | 177 | # Retrieve prompt text by its id 178 | def prompt_text(prompt_id) 179 | read_file(file_path(prompt_id, prompt_extension)) 180 | end 181 | 182 | # Retrieve parameter values by its id 183 | def parameter_values(prompt_id) 184 | # Parse parameters from the prompt text 185 | prompt_text_content = prompt_text(prompt_id) 186 | parsed_parameters = parse_parameters_from_text(prompt_text_content) 187 | 188 | # Load parameters from JSON file if it exists 189 | params_path = file_path(prompt_id, params_extension) 190 | file_parameters = params_path.exist? ? deserialize(read_file(params_path)) : {} 191 | 192 | # Only preserve JSON values for parameters that exist in the current text 193 | parsed_parameters.each_key do |key| 194 | if file_parameters.key?(key) && file_parameters[key].is_a?(Array) 195 | parsed_parameters[key] = file_parameters[key] 196 | end 197 | end 198 | 199 | parsed_parameters 200 | end 201 | 202 | # Parse parameters from the prompt text 203 | def parse_parameters_from_text(text) 204 | parameters = {} 205 | 206 | text.scan(PromptManager::Prompt.parameter_regex).each do |match| 207 | variable_name = match.shift 208 | parameters[variable_name] = [] unless parameters.key?(variable_name) 209 | end 210 | 211 | parameters 212 | end 213 | 214 | # Save prompt text and parameter values to corresponding files 215 | def save( 216 | id:, 217 | text: "", 218 | parameters: {} 219 | ) 220 | validate_id(id) 221 | 222 | prompt_filepath = file_path(id, prompt_extension) 223 | params_filepath = file_path(id, params_extension) 224 | 225 | write_with_error_handling(prompt_filepath, text) 226 | write_with_error_handling(params_filepath, serialize(parameters)) 227 | end 228 | 229 | # Delete prompt text and parameter values files 230 | def delete(id:) 231 | validate_id(id) 232 | 233 | prompt_filepath = file_path(id, prompt_extension) 234 | params_filepath = file_path(id, params_extension) 235 | 236 | delete_with_error_handling(prompt_filepath) 237 | delete_with_error_handling(params_filepath) 238 | end 239 | 240 | # Search for prompts 241 | def search(for_what) 242 | search_term = for_what.downcase 243 | 244 | if search_proc.is_a? Proc 245 | search_proc.call(search_term) 246 | else 247 | search_prompts(search_term) 248 | end 249 | end 250 | 251 | # Return an Array of prompt IDs 252 | def list(*) 253 | prompt_ids = [] 254 | 255 | Pathname.glob(prompts_dir.join("**/*#{prompt_extension}")).each do |file_path| 256 | prompt_id = file_path.relative_path_from(prompts_dir).to_s.gsub(prompt_extension, '') 257 | prompt_ids << prompt_id 258 | end 259 | 260 | prompt_ids.sort 261 | end 262 | 263 | # Returns a Pathname object for a prompt ID text file 264 | # However, it is possible that the file does not exist. 265 | def path(id) 266 | validate_id(id) 267 | file_path(id, prompt_extension) 268 | end 269 | 270 | ########################################## 271 | private 272 | 273 | # Validate that the ID contains good characters. 274 | def validate_id(id) 275 | raise ArgumentError, "Invalid ID format id: #{id}" unless id =~ PROMPT_ID_FORMAT 276 | end 277 | 278 | # Verify that the ID exists 279 | def verify_id(id) 280 | unless file_path(id, prompt_extension).exist? 281 | raise ArgumentError, "Invalid prompt_id: #{id}" 282 | end 283 | end 284 | 285 | # Write to a file with error handling 286 | def write_with_error_handling(file_path, content) 287 | begin 288 | file_path.write content 289 | true 290 | rescue IOError => e 291 | raise "Failed to write to file: #{e.message}" 292 | end 293 | end 294 | 295 | # Delete a file with error handling 296 | def delete_with_error_handling(file_path) 297 | begin 298 | file_path.delete 299 | true 300 | rescue IOError => e 301 | raise "Failed to delete file: #{e.message}" 302 | end 303 | end 304 | 305 | # Get the file path for a prompt ID and extension 306 | def file_path(id, extension) 307 | prompts_dir + "#{id}#{extension}" 308 | end 309 | 310 | # Read a file 311 | def read_file(full_path) 312 | raise IOError, 'File does not exist' unless File.exist?(full_path) 313 | File.read(full_path) 314 | end 315 | 316 | # Search for prompts 317 | def search_prompts(search_term) 318 | prompt_ids = [] 319 | 320 | Pathname.glob(prompts_dir.join("**/*#{prompt_extension}")).each do |prompt_path| 321 | if prompt_path.read.downcase.include?(search_term) 322 | prompt_id = prompt_path.relative_path_from(prompts_dir).to_s.gsub(prompt_extension, '') 323 | prompt_ids << prompt_id 324 | end 325 | end 326 | 327 | prompt_ids.sort 328 | end 329 | 330 | # Serialize data to JSON 331 | def serialize(data) 332 | data.to_json 333 | end 334 | 335 | # Deserialize JSON data 336 | def deserialize(data) 337 | JSON.parse(data) 338 | end 339 | end 340 | -------------------------------------------------------------------------------- /docs/api/directive-processor.md: -------------------------------------------------------------------------------- 1 | # Directive Processor API Reference 2 | 3 | The Directive Processor handles special instructions in prompts that begin with `//` and enable powerful prompt composition capabilities. 4 | 5 | ## Core Classes 6 | 7 | ### `PromptManager::DirectiveProcessor` 8 | 9 | The main class responsible for processing directives within prompts. 10 | 11 | #### Constructor 12 | 13 | ```ruby 14 | processor = PromptManager::DirectiveProcessor.new( 15 | storage: storage_adapter, 16 | max_depth: 10, 17 | timeout: 30 18 | ) 19 | ``` 20 | 21 | **Parameters:** 22 | - `storage` (Storage::Base): Storage adapter for resolving includes 23 | - `max_depth` (Integer): Maximum include depth to prevent circular references (default: 10) 24 | - `timeout` (Numeric): Processing timeout in seconds (default: 30) 25 | 26 | #### Instance Methods 27 | 28 | ##### `process(content, context = {})` 29 | 30 | Processes all directives in the given content. 31 | 32 | **Parameters:** 33 | - `content` (String): The prompt content containing directives 34 | - `context` (Hash): Processing context and variables 35 | 36 | **Returns:** String - Processed content with directives resolved 37 | 38 | **Raises:** 39 | - `PromptManager::DirectiveProcessingError` - If directive processing fails 40 | - `PromptManager::CircularIncludeError` - If circular includes are detected 41 | 42 | ```ruby 43 | processor = PromptManager::DirectiveProcessor.new(storage: adapter) 44 | result = processor.process("//include header.txt\nHello World!") 45 | ``` 46 | 47 | ##### `register_directive(name, handler)` 48 | 49 | Registers a custom directive handler. 50 | 51 | **Parameters:** 52 | - `name` (String): Directive name (without //) 53 | - `handler` (Proc): Handler that processes the directive 54 | 55 | ```ruby 56 | processor.register_directive('timestamp') do |args, context| 57 | Time.current.strftime('%Y-%m-%d %H:%M:%S') 58 | end 59 | ``` 60 | 61 | ## Built-in Directives 62 | 63 | ### `//include` (alias: `//import`) 64 | 65 | Includes content from another prompt file. 66 | 67 | **Syntax:** 68 | ```text 69 | //include path/to/file.txt 70 | //include [VARIABLE_PATH].txt 71 | //import common/header.txt 72 | ``` 73 | 74 | **Features:** 75 | - Parameter substitution in paths: `//include templates/[TEMPLATE_TYPE].txt` 76 | - Relative and absolute path resolution 77 | - Circular include detection 78 | - Nested include support 79 | 80 | **Examples:** 81 | 82 | ```text 83 | # Basic include 84 | //include common/header.txt 85 | 86 | # With parameter substitution 87 | //include templates/[EMAIL_TYPE].txt 88 | 89 | # Nested directory structure 90 | //include emails/marketing/[CAMPAIGN_TYPE]/template.txt 91 | ``` 92 | 93 | ### `//set` 94 | 95 | Sets variables for use within the current prompt. 96 | 97 | **Syntax:** 98 | ```text 99 | //set VARIABLE_NAME value 100 | //set CURRENT_DATE <%= Date.today %> 101 | ``` 102 | 103 | **Examples:** 104 | 105 | ```text 106 | //set COMPANY_NAME Acme Corporation 107 | //set SUPPORT_EMAIL support@[COMPANY_DOMAIN] 108 | //set GREETING Hello [CUSTOMER_NAME] 109 | 110 | Your message: [GREETING] 111 | Contact us: [SUPPORT_EMAIL] 112 | ``` 113 | 114 | ### `//if` / `//endif` 115 | 116 | Conditional content inclusion. 117 | 118 | **Syntax:** 119 | ```text 120 | //if CONDITION 121 | content to include if condition is true 122 | //endif 123 | ``` 124 | 125 | **Examples:** 126 | 127 | ```text 128 | //if [USER_TYPE] == 'premium' 129 | 🌟 Premium features are available! 130 | //endif 131 | 132 | //if [ORDER_TOTAL] > 100 133 | 🚚 Free shipping applied! 134 | //endif 135 | ``` 136 | 137 | ## Custom Directive Development 138 | 139 | ### Simple Directive Handler 140 | 141 | ```ruby 142 | # Register a simple directive 143 | processor.register_directive('upper') do |args, context| 144 | args.upcase 145 | end 146 | 147 | # Usage in prompt: 148 | # //upper hello world 149 | # Result: HELLO WORLD 150 | ``` 151 | 152 | ### Complex Directive Handler 153 | 154 | ```ruby 155 | # Register directive with parameter processing 156 | processor.register_directive('format_currency') do |args, context| 157 | amount, currency = args.split(',').map(&:strip) 158 | formatted_amount = sprintf('%.2f', amount.to_f) 159 | 160 | case currency.downcase 161 | when 'usd', '$' 162 | "$#{formatted_amount}" 163 | when 'eur', '€' 164 | "€#{formatted_amount}" 165 | else 166 | "#{formatted_amount} #{currency}" 167 | end 168 | end 169 | 170 | # Usage in prompt: 171 | # //format_currency [ORDER_TOTAL], USD 172 | # Result: $123.45 173 | ``` 174 | 175 | ### Directive with Context Access 176 | 177 | ```ruby 178 | processor.register_directive('user_greeting') do |args, context| 179 | user_name = context.dig(:parameters, :user_name) || 'Guest' 180 | time_of_day = Time.current.hour < 12 ? 'morning' : 'afternoon' 181 | 182 | "Good #{time_of_day}, #{user_name}!" 183 | end 184 | 185 | # Usage in prompt: 186 | # //user_greeting 187 | # Result: Good morning, Alice! 188 | ``` 189 | 190 | ## Error Handling 191 | 192 | ### Directive Processing Errors 193 | 194 | ```ruby 195 | begin 196 | result = processor.process(content) 197 | rescue PromptManager::DirectiveProcessingError => e 198 | puts "Directive error at line #{e.line_number}: #{e.message}" 199 | puts "Directive: #{e.directive}" 200 | rescue PromptManager::CircularIncludeError => e 201 | puts "Circular include detected: #{e.include_chain.join(' -> ')}" 202 | end 203 | ``` 204 | 205 | ### Custom Error Handling 206 | 207 | ```ruby 208 | processor.register_directive('safe_include') do |args, context| 209 | begin 210 | storage.read(args) 211 | rescue PromptManager::PromptNotFoundError 212 | "" 213 | end 214 | end 215 | ``` 216 | 217 | ## Advanced Features 218 | 219 | ### Conditional Directives 220 | 221 | ```ruby 222 | processor.register_directive('feature_flag') do |args, context| 223 | feature_name, content = args.split(':', 2) 224 | 225 | if FeatureFlag.enabled?(feature_name) 226 | processor.process(content.strip, context) 227 | else 228 | '' 229 | end 230 | end 231 | 232 | # Usage: 233 | # //feature_flag new_ui: Welcome to our new interface! 234 | ``` 235 | 236 | ### Loop Directives 237 | 238 | ```ruby 239 | processor.register_directive('foreach') do |args, context| 240 | array_name, template = args.split(':', 2) 241 | array_data = context.dig(:parameters, array_name.to_sym) || [] 242 | 243 | array_data.map.with_index do |item, index| 244 | item_context = context.merge( 245 | parameters: context[:parameters].merge( 246 | item: item, 247 | index: index, 248 | first: index == 0, 249 | last: index == array_data.length - 1 250 | ) 251 | ) 252 | processor.process(template.strip, item_context) 253 | end.join("\n") 254 | end 255 | 256 | # Usage: 257 | # //foreach items: - [ITEM.NAME]: $[ITEM.PRICE] 258 | ``` 259 | 260 | ### Template Inheritance 261 | 262 | ```ruby 263 | class TemplateInheritanceProcessor < PromptManager::DirectiveProcessor 264 | def initialize(**options) 265 | super(**options) 266 | register_built_in_directives 267 | end 268 | 269 | private 270 | 271 | def register_built_in_directives 272 | register_directive('extends') do |args, context| 273 | parent_content = storage.read(args) 274 | context[:parent_content] = parent_content 275 | '' # Don't include anything at this point 276 | end 277 | 278 | register_directive('block') do |args, context| 279 | block_name, content = args.split(':', 2) 280 | context[:blocks] ||= {} 281 | context[:blocks][block_name] = content.strip 282 | '' # Blocks are processed later 283 | end 284 | 285 | register_directive('yield') do |args, context| 286 | block_name = args.strip 287 | context.dig(:blocks, block_name) || '' 288 | end 289 | end 290 | 291 | def process(content, context = {}) 292 | # First pass: extract blocks and parent template 293 | super(content, context) 294 | 295 | # Second pass: process parent template with blocks 296 | if context[:parent_content] 297 | super(context[:parent_content], context) 298 | else 299 | super(content, context) 300 | end 301 | end 302 | end 303 | 304 | # Usage: 305 | # child.txt: 306 | # //extends parent.txt 307 | # //block content: This is child content 308 | # //block title: Child Page 309 | 310 | # parent.txt: 311 | #

//yield title

312 | #
//yield content
313 | ``` 314 | 315 | ## Configuration 316 | 317 | ### Global Configuration 318 | 319 | ```ruby 320 | PromptManager.configure do |config| 321 | config.directive_processor_class = CustomDirectiveProcessor 322 | config.max_include_depth = 5 323 | config.directive_timeout = 60 324 | end 325 | ``` 326 | 327 | ### Custom Processor 328 | 329 | ```ruby 330 | class CustomDirectiveProcessor < PromptManager::DirectiveProcessor 331 | def initialize(**options) 332 | super(**options) 333 | register_custom_directives 334 | end 335 | 336 | private 337 | 338 | def register_custom_directives 339 | register_directive('env') { |args, context| ENV[args] } 340 | register_directive('random') { |args, context| rand(args.to_i) } 341 | register_directive('uuid') { |args, context| SecureRandom.uuid } 342 | end 343 | end 344 | ``` 345 | 346 | ## Performance Optimization 347 | 348 | ### Caching Directive Results 349 | 350 | ```ruby 351 | class CachedDirectiveProcessor < PromptManager::DirectiveProcessor 352 | def initialize(**options) 353 | super(**options) 354 | @directive_cache = {} 355 | end 356 | 357 | def register_directive(name, &handler) 358 | cached_handler = lambda do |args, context| 359 | cache_key = "#{name}:#{args}:#{context.hash}" 360 | 361 | @directive_cache[cache_key] ||= handler.call(args, context) 362 | end 363 | 364 | super(name, &cached_handler) 365 | end 366 | 367 | def clear_cache 368 | @directive_cache.clear 369 | end 370 | end 371 | ``` 372 | 373 | ### Parallel Processing 374 | 375 | ```ruby 376 | class ParallelDirectiveProcessor < PromptManager::DirectiveProcessor 377 | def process_includes(content, context) 378 | includes = extract_includes(content) 379 | 380 | # Process includes in parallel 381 | results = Parallel.map(includes) do |include_directive| 382 | process_single_include(include_directive, context) 383 | end 384 | 385 | # Replace includes with results 386 | replace_includes(content, includes, results) 387 | end 388 | end 389 | ``` 390 | 391 | ## Testing Directives 392 | 393 | ### RSpec Examples 394 | 395 | ```ruby 396 | describe 'Custom Directive' do 397 | let(:processor) { PromptManager::DirectiveProcessor.new(storage: storage) } 398 | let(:storage) { instance_double(PromptManager::Storage::Base) } 399 | 400 | before do 401 | processor.register_directive('test') do |args, context| 402 | "processed: #{args}" 403 | end 404 | end 405 | 406 | it 'processes custom directive' do 407 | content = "//test hello world" 408 | result = processor.process(content) 409 | 410 | expect(result).to eq "processed: hello world" 411 | end 412 | 413 | it 'handles directive errors gracefully' do 414 | processor.register_directive('error') { |args, context| raise 'test error' } 415 | 416 | expect { 417 | processor.process("//error test") 418 | }.to raise_error(PromptManager::DirectiveProcessingError) 419 | end 420 | end 421 | ``` 422 | 423 | ## Best Practices 424 | 425 | 1. **Error Handling**: Always handle errors gracefully in directive handlers 426 | 2. **Performance**: Cache expensive operations in directive handlers 427 | 3. **Security**: Validate and sanitize directive arguments 428 | 4. **Documentation**: Document custom directive syntax and behavior 429 | 5. **Testing**: Write comprehensive tests for custom directives 430 | 6. **Naming**: Use descriptive names for custom directives 431 | 7. **Context**: Use context parameter to access prompt rendering state --------------------------------------------------------------------------------