prompt_manager 0.5.7 → 0.5.8

data/docs/examples.md

@@ -0,0 +1,337 @@
+# Examples
+
+This section provides comprehensive examples demonstrating various features and use cases of PromptManager.
+
+## Basic Usage
+
+The simplest way to get started with PromptManager:
+
+```ruby
+# examples/simple.rb
+require 'prompt_manager'
+
+# Configure storage adapter
+PromptManager::Prompt.storage_adapter =
+  PromptManager::Storage::FileSystemAdapter.config do |config|
+    config.prompts_dir = '~/.prompts'
+  end.new
+
+# Create and use a prompt
+prompt = PromptManager::Prompt.new(id: 'greeting')
+prompt.parameters = {
+  "[NAME]" => "Alice",
+  "[LANGUAGE]" => "English"
+}
+
+# Get the processed prompt text
+puts prompt.to_s
+```
+
+## Advanced Integration with LLM and Streaming
+
+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:
+
+### Features Demonstrated
+
+- **ERB templating** for dynamic content generation
+- **Shell integration** for environment variable substitution  
+- **OpenAI API integration** with streaming responses
+- **Professional UI** with spinner feedback using `tty-spinner`
+- **Real-time streaming** of LLM responses
+
+### Code Overview
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'prompt_manager'
+  gem 'ruby-openai'
+  gem 'tty-spinner'
+end
+
+require 'prompt_manager'
+require 'openai'
+require 'erb'
+require 'time'
+require 'tty-spinner'
+
+# Configure PromptManager with filesystem adapter
+PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.config do |config|
+  config.prompts_dir = File.join(__dir__, 'prompts_dir')
+end.new
+
+# Configure OpenAI client
+client = OpenAI::Client.new(
+  access_token: ENV['OPENAI_API_KEY']
+)
+
+# Get prompt instance with advanced features enabled
+prompt = PromptManager::Prompt.new(
+  id: 'advanced_demo',
+  erb_flag: true,    # Enable ERB templating
+  envar_flag: true   # Enable environment variable substitution
+)
+
+# Show spinner while waiting for response
+spinner = TTY::Spinner.new("[:spinner] Waiting for response...")
+spinner.auto_spin
+
+# Stream the response from OpenAI
+response = client.chat(
+  parameters: {
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: prompt.to_s }],
+    stream: proc do |chunk, _bytesize|
+      spinner.stop
+      content = chunk.dig("choices", 0, "delta", "content")
+      print content if content
+      $stdout.flush
+    end
+  }
+)
+
+puts
+```
+
+### Prompt Template
+
+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:
+
+```text
+# System Analysis and Historical Comparison Report
+# Generated with PromptManager - ERB + Shell Integration Demo
+
+```markdown
+## Current System Information
+
+**Timestamp**: <%= Time.now.strftime('%A, %B %d, %Y at %I:%M:%S %p %Z') %>
+**Analysis Duration**: <%= Time.now - Time.parse('2024-01-01') %> seconds since 2024 began
+
+### Hardware Platform Details
+**Architecture**: $HOSTTYPE$MACHTYPE
+**Hostname**: $HOSTNAME  
+**Operating System**: $OSTYPE
+**Shell**: $SHELL (version: $BASH_VERSION)
+**User**: $USER
+**Home Directory**: $HOME
+**Current Path**: $PWD
+**Terminal**: $TERM
+
+### Detailed System Profile
+<% if RUBY_PLATFORM.include?('darwin') %>
+**Platform**: macOS/Darwin System
+**Ruby Platform**: <%= RUBY_PLATFORM %>
+**Ruby Version**: <%= RUBY_VERSION %>
+**Ruby Engine**: <%= RUBY_ENGINE %>
+<% elsif RUBY_PLATFORM.include?('linux') %>
+**Platform**: Linux System  
+**Ruby Platform**: <%= RUBY_PLATFORM %>
+**Ruby Version**: <%= RUBY_VERSION %>
+**Ruby Engine**: <%= RUBY_ENGINE %>
+<% else %>
+**Platform**: Other Unix-like System
+**Ruby Platform**: <%= RUBY_PLATFORM %>
+**Ruby Version**: <%= RUBY_VERSION %>
+**Ruby Engine**: <%= RUBY_ENGINE %>
+<% end %>
+
+### Performance Context
+**Load Average**: <%= `uptime`.strip rescue 'Unable to determine' %>
+**Memory Info**: <%= `vm_stat | head -5`.strip rescue 'Unable to determine' if RUBY_PLATFORM.include?('darwin') %>
+**Disk Usage**: <%= `df -h / | tail -1`.strip rescue 'Unable to determine' %>
+
+## Analysis Request
+
+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).
+```
+
+### Key Benefits
+
+1. **Dynamic Content**: ERB templating allows for real-time system information gathering
+2. **Environment Awareness**: Shell integration provides current system context
+3. **Professional UX**: Spinner provides visual feedback during API calls  
+4. **Real-time Streaming**: Users see responses as they're generated
+5. **Comprehensive Analysis**: The prompt generates detailed technical comparisons
+
+## Search Integration
+
+See [using_search_proc.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/using_search_proc.rb) for advanced search capabilities:
+
+```ruby
+# Configure custom search with ripgrep
+PromptManager::Storage::FileSystemAdapter.config do |config|
+  config.prompts_dir = '~/.prompts'
+  config.search_proc = ->(query) {
+    # Use ripgrep for fast searching
+    `rg -l "#{query}" #{config.prompts_dir}`.split("\n")
+      .map { |path| File.basename(path, '.txt') }
+  }
+end.new
+
+# Search for prompts containing specific terms
+results = PromptManager::Prompt.search("database queries")
+puts "Found prompts: #{results.join(', ')}"
+```
+
+## Parameter Management
+
+### Basic Parameters
+
+```ruby
+prompt = PromptManager::Prompt.new(id: 'template')
+prompt.parameters = {
+  "[NAME]" => "John",
+  "[ROLE]" => "developer",
+  "[PROJECT]" => "web application"
+}
+```
+
+### Parameter History
+
+```ruby
+# Parameters support history tracking
+prompt.parameters = {
+  "[NAME]" => ["Alice", "Bob", "Charlie"]  # Charlie is most recent
+}
+
+# Access current value
+current_name = prompt.parameters["[NAME]"].last
+
+# Access history
+name_history = prompt.parameters["[NAME]"]
+```
+
+## Custom Storage Adapters
+
+### Redis Storage Example
+
+```ruby
+require 'redis'
+require 'json'
+
+class RedisAdapter
+  def initialize(redis_client)
+    @redis = redis_client
+  end
+
+  def get(id:)
+    {
+      id: id,
+      text: @redis.get("prompt:#{id}:text") || "",
+      parameters: JSON.parse(@redis.get("prompt:#{id}:params") || '{}')
+    }
+  end
+
+  def save(id:, text:, parameters:)
+    @redis.set("prompt:#{id}:text", text)
+    @redis.set("prompt:#{id}:params", parameters.to_json)
+  end
+
+  def delete(id:)
+    @redis.del("prompt:#{id}:text", "prompt:#{id}:params")
+  end
+
+  def search(query)
+    # Simple search implementation
+    @redis.keys("prompt:*:text").select do |key|
+      content = @redis.get(key)
+      content&.include?(query)
+    end.map { |key| key.split(':')[1] }
+  end
+
+  def list
+    @redis.keys("prompt:*:text").map { |key| key.split(':')[1] }
+  end
+end
+
+# Usage
+redis = Redis.new
+PromptManager::Prompt.storage_adapter = RedisAdapter.new(redis)
+```
+
+## Directive Processing
+
+### Custom Directives
+
+```ruby
+class CustomDirectiveProcessor < PromptManager::DirectiveProcessor
+  def process_directive(directive, prompt)
+    case directive
+    when /^\/\/model (.+)$/
+      set_model($1)
+    when /^\/\/temperature (.+)$/
+      set_temperature($1.to_f)
+    when /^\/\/max_tokens (\d+)$/
+      set_max_tokens($1.to_i)
+    else
+      super  # Handle built-in directives
+    end
+  end
+
+  private
+
+  def set_model(model)
+    @model = model
+  end
+
+  def set_temperature(temp)
+    @temperature = temp
+  end
+
+  def set_max_tokens(tokens)
+    @max_tokens = tokens
+  end
+end
+
+# Usage
+prompt = PromptManager::Prompt.new(
+  id: 'ai_prompt',
+  directives_processor: CustomDirectiveProcessor.new
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  prompt = PromptManager::Prompt.new(id: 'nonexistent')
+  result = prompt.to_s
+rescue PromptManager::StorageError => e
+  puts "Storage error: #{e.message}"
+rescue PromptManager::ParameterError => e
+  puts "Parameter error: #{e.message}"
+rescue PromptManager::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+end
+```
+
+## Testing Integration
+
+```ruby
+# Test helper for prompt testing
+def test_prompt(id, params = {})
+  prompt = PromptManager::Prompt.new(id: id)
+  prompt.parameters = params
+  prompt.to_s
+end
+
+# Example test
+describe "greeting prompt" do
+  it "personalizes the greeting" do
+    result = test_prompt('greeting', {
+      "[NAME]" => "Alice",
+      "[TIME]" => "morning"
+    })
+    
+    expect(result).to include("Hello Alice")
+    expect(result).to include("Good morning")
+  end
+end
+```
+
+For more examples and advanced usage patterns, see the complete examples in the [examples/](https://github.com/MadBomber/prompt_manager/tree/main/examples) directory.

data/docs/getting-started/basic-concepts.md

@@ -0,0 +1,318 @@
+# Basic Concepts
+
+Understanding these core concepts will help you make the most of PromptManager.
+
+## The Prompt Lifecycle
+
+Every prompt in PromptManager follows a predictable lifecycle:
+
+```mermaid
+graph TD
+    A[Create/Load Prompt] --> B[Parse Keywords]
+    B --> C[Set Parameters]
+    C --> D[Process Directives]
+    D --> E[Apply ERB Templates]
+    E --> F[Substitute Variables]
+    F --> G[Generate Final Text]
+    G --> H[Save Changes]
+```
+
+## Core Components
+
+### 1. Prompts
+
+A **Prompt** is the central entity in PromptManager. It represents a template with:
+
+- **Text content** with embedded keywords
+- **Parameters** (values for keywords)
+- **Metadata** (directives, comments, configuration)
+
+```ruby
+prompt = PromptManager::Prompt.new(
+  id: 'example',           # Unique identifier
+  erb_flag: true,          # Enable ERB processing
+  envar_flag: true         # Enable environment variables
+)
+```
+
+### 2. Keywords
+
+**Keywords** are placeholders in your prompt text that get replaced with actual values:
+
+```text
+Hello [NAME], today is [DATE] and the weather is [WEATHER].
+```
+
+Default keyword format: `[UPPERCASE_WITH_UNDERSCORES]`
+
+You can customize this pattern:
+
+```ruby
+# Use {{mustache}} style
+PromptManager::Prompt.parameter_regex = /(\{\{[a-z_]+\}\})/
+
+# Use :symbol style  
+PromptManager::Prompt.parameter_regex = /(:[a-z_]+)/
+```
+
+### 3. Parameters
+
+**Parameters** are the actual values that replace keywords:
+
+```ruby
+prompt.parameters = {
+  "[NAME]" => "Alice",
+  "[DATE]" => Date.today.to_s,
+  "[WEATHER]" => "sunny"
+}
+```
+
+Since v0.3.0, parameters store history as arrays:
+
+```ruby
+prompt.parameters = {
+  "[NAME]" => ["Alice", "Bob", "Charlie"]  # Charlie is most recent
+}
+```
+
+### 4. Storage Adapters
+
+**Storage Adapters** handle how prompts are persisted:
+
+=== "FileSystem"
+
+    ```ruby
+    PromptManager::Storage::FileSystemAdapter.config do |config|
+      config.prompts_dir = '~/.prompts'
+      config.prompt_extension = '.txt'
+      config.params_extension = '.json'
+    end
+    ```
+
+=== "ActiveRecord"
+
+    ```ruby
+    PromptManager::Storage::ActiveRecordAdapter.config do |config|
+      config.model = PromptModel
+      config.id_column = :name
+      config.text_column = :content
+      config.parameters_column = :params
+    end
+    ```
+
+### 5. Directives
+
+**Directives** are special instructions that start with `//`:
+
+```text
+//include common/header.txt
+//import templates/[TEMPLATE_TYPE].txt
+
+Your main prompt content here...
+```
+
+## File Structure (FileSystem Adapter)
+
+When using the FileSystem adapter, your prompts are organized like this:
+
+```
+~/.prompts/
+├── greeting.txt              # Prompt text
+├── greeting.json             # Parameters
+├── translation.txt
+├── translation.json
+└── common/
+    ├── header.txt            # Shared components
+    └── footer.txt
+```
+
+### Prompt Files (`.txt`)
+
+```text title="greeting.txt"
+# Description: Friendly greeting prompt
+# Tags: customer-service, greeting
+# Version: 1.2
+
+//include common/header.txt
+
+Hello [CUSTOMER_NAME]!
+
+Thank you for contacting [COMPANY_NAME]. I'm here to help you with 
+[REQUEST_TYPE]. Let me know how I can assist you today.
+
+Best regards,
+[AGENT_NAME]
+
+__END__
+Internal notes: This prompt is used for all initial customer contacts.
+Update the company name parameter when client changes.
+```
+
+### Parameter Files (`.json`)
+
+```json title="greeting.json"
+{
+  "[CUSTOMER_NAME]": ["Alice Johnson", "Bob Smith"],
+  "[COMPANY_NAME]": ["Acme Corp"],
+  "[REQUEST_TYPE]": ["general inquiry", "technical support", "billing"],
+  "[AGENT_NAME]": ["Sarah", "Mike", "Jennifer"]
+}
+```
+
+## Processing Pipeline
+
+PromptManager processes prompts through several stages:
+
+### 1. Text Loading
+- Load raw prompt text from storage
+- Parse out comments and `__END__` sections
+
+### 2. Keyword Extraction  
+- Scan text for keyword patterns
+- Build list of required parameters
+
+### 3. Directive Processing
+- Process `//include` and `//import` directives
+- Handle loop protection for circular includes
+- Substitute keywords in directive paths
+
+### 4. Template Processing
+- Apply ERB templates if `erb_flag` is true
+- Substitute environment variables if `envar_flag` is true
+
+### 5. Parameter Substitution
+- Replace keywords with parameter values
+- Handle missing parameters (error or warning)
+
+### 6. Final Assembly
+- Combine processed components
+- Return final prompt text
+
+## Error Handling
+
+PromptManager provides specific error types:
+
+```ruby
+begin
+  prompt = PromptManager::Prompt.new(id: 'example')
+  puts prompt.to_s
+rescue PromptManager::StorageError => e
+  puts "Storage problem: #{e.message}"
+rescue PromptManager::ParameterError => e  
+  puts "Parameter issue: #{e.message}"
+rescue PromptManager::ConfigurationError => e
+  puts "Config problem: #{e.message}"
+end
+```
+
+### Common Error Scenarios
+
+| Error Type | Common Cause | Solution |
+|------------|--------------|----------|
+| `StorageError` | File not found, permission denied | Check file paths and permissions |
+| `ParameterError` | Missing parameter value | Set all required parameters |
+| `ConfigurationError` | Invalid adapter config | Review adapter configuration |
+
+## Best Practices
+
+### 1. Organize Your Prompts
+
+```
+prompts/
+├── common/              # Shared components
+│   ├── headers/
+│   ├── footers/
+│   └── signatures/
+├── customer-service/    # Domain-specific prompts
+├── technical/
+└── templates/           # Reusable templates
+```
+
+### 2. Use Meaningful Keywords
+
+```text
+# Good - descriptive and clear
+[CUSTOMER_NAME], [ORDER_NUMBER], [DELIVERY_DATE]
+
+# Avoid - unclear abbreviations  
+[CN], [ON], [DD]
+```
+
+### 3. Document Your Prompts
+
+```text
+# Description: What this prompt does
+# Tags: classification, tags
+# Version: 1.0
+# Author: Your Name
+# Last Updated: 2024-01-15
+
+//include common/disclaimer.txt
+
+Your prompt content...
+
+__END__
+Internal notes, change history, and documentation go here.
+This section is ignored by the processor.
+```
+
+### 4. Version Your Parameters
+
+```json
+{
+  "_meta": {
+    "version": "1.0",
+    "updated": "2024-01-15",
+    "notes": "Added new product categories"
+  },
+  "[CATEGORY]": ["electronics", "books", "clothing"]
+}
+```
+
+## Advanced Concepts
+
+### Parameter Validation
+
+```ruby
+# Custom validation in your application
+def validate_parameters(prompt)
+  required = prompt.keywords
+  provided = prompt.parameters.keys
+  missing = required - provided
+  
+  raise "Missing parameters: #{missing.join(', ')}" unless missing.empty?
+end
+```
+
+### Dynamic Prompts
+
+```text
+# Template selection based on parameters
+//include templates/[TEMPLATE_TYPE].txt
+
+# Conditional content using ERB
+<% if '[URGENCY]' == 'high' %>
+🚨 URGENT: Immediate attention required
+<% end %>
+```
+
+### Search Integration
+
+```ruby
+# Configure custom search
+adapter.search_proc = ->(query) {
+  # Use ripgrep for fast search
+  `rg -l "#{query}" #{prompts_dir}`.split("\n").map { |f| 
+    File.basename(f, '.txt') 
+  }
+}
+```
+
+## Next Steps
+
+Now that you understand the basics:
+
+1. **Try the examples** in [Core Features](../core-features/parameterized-prompts.md)
+2. **Choose a storage adapter** in [Storage Adapters](../storage/overview.md)  
+3. **Explore advanced features** in [Advanced Usage](../advanced/custom-keywords.md)
+4. **See real applications** in [Examples](../examples/basic.md)