prompt_manager 0.5.7 → 0.5.8

data/docs/api/storage-adapters.md

@@ -0,0 +1,462 @@
+# Storage Adapters API Reference
+
+PromptManager uses a storage adapter pattern to provide flexible backends for prompt storage and retrieval.
+
+## Base Storage Adapter
+
+All storage adapters inherit from `PromptManager::Storage::Base` and must implement the core interface.
+
+### `PromptManager::Storage::Base`
+
+The abstract base class that defines the storage adapter interface.
+
+#### Required Methods
+
+##### `read(prompt_id)`
+
+Reads prompt content from storage.
+
+**Parameters:**
+- `prompt_id` (String): Unique identifier for the prompt
+
+**Returns:** String - The prompt content
+
+**Raises:**
+- `PromptManager::PromptNotFoundError` - If prompt doesn't exist
+- `PromptManager::StorageError` - For storage-related errors
+
+```ruby
+def read(prompt_id)
+  # Implementation must return prompt content as string
+  # or raise PromptNotFoundError if not found
+end
+```
+
+##### `write(prompt_id, content)`
+
+Writes prompt content to storage.
+
+**Parameters:**
+- `prompt_id` (String): Unique identifier for the prompt
+- `content` (String): The prompt content to store
+
+**Returns:** Boolean - True on success
+
+**Raises:**
+- `PromptManager::StorageError` - For storage-related errors
+
+```ruby
+def write(prompt_id, content)
+  # Implementation must store content and return true
+  # or raise StorageError on failure
+end
+```
+
+##### `exist?(prompt_id)`
+
+Checks if a prompt exists in storage.
+
+**Parameters:**
+- `prompt_id` (String): Unique identifier for the prompt
+
+**Returns:** Boolean - True if prompt exists
+
+```ruby
+def exist?(prompt_id)
+  # Implementation must return boolean
+end
+```
+
+##### `delete(prompt_id)`
+
+Removes a prompt from storage.
+
+**Parameters:**
+- `prompt_id` (String): Unique identifier for the prompt
+
+**Returns:** Boolean - True if successfully deleted
+
+```ruby
+def delete(prompt_id)
+  # Implementation must remove prompt and return success status
+end
+```
+
+##### `list`
+
+Returns all available prompt identifiers.
+
+**Returns:** Array<String> - Array of prompt IDs
+
+```ruby
+def list
+  # Implementation must return array of all prompt IDs
+end
+```
+
+#### Optional Methods
+
+##### `initialize(**options)`
+
+Constructor for storage adapter configuration.
+
+```ruby
+def initialize(**options)
+  super
+  # Custom initialization logic
+end
+```
+
+##### `clear`
+
+Removes all prompts from storage (optional).
+
+**Returns:** Boolean - True on success
+
+```ruby
+def clear
+  # Optional: implement to support clearing all prompts
+end
+```
+
+## Built-in Storage Adapters
+
+### FileSystemAdapter
+
+Stores prompts as files in a directory structure.
+
+```ruby
+adapter = PromptManager::Storage::FileSystemAdapter.new(
+  prompts_dir: '/path/to/prompts',
+  file_extensions: ['.txt', '.md', '.prompt'],
+  create_directories: true
+)
+```
+
+**Configuration Options:**
+
+- `prompts_dir` (String|Array): Directory path(s) to search
+- `file_extensions` (Array): File extensions to recognize (default: `['.txt', '.md']`)
+- `create_directories` (Boolean): Create directories if they don't exist (default: `true`)
+
+**Features:**
+- Hierarchical prompt organization with subdirectories
+- Multiple search paths with fallback
+- Automatic file extension detection
+- Thread-safe file operations
+
+### ActiveRecordAdapter
+
+Stores prompts in a database using ActiveRecord.
+
+```ruby
+adapter = PromptManager::Storage::ActiveRecordAdapter.new(
+  model_class: Prompt,
+  id_column: :prompt_id,
+  content_column: :content,
+  scope: -> { where(active: true) }
+)
+```
+
+**Configuration Options:**
+
+- `model_class` (Class): ActiveRecord model class
+- `id_column` (Symbol): Column containing prompt ID (default: `:prompt_id`)
+- `content_column` (Symbol): Column containing prompt content (default: `:content`)
+- `scope` (Proc): Additional query scope (optional)
+
+**Features:**
+- Full database integration with Rails
+- Transaction support
+- Query optimization
+- Multi-tenancy support
+
+## Custom Adapter Implementation
+
+### Example: MemoryAdapter
+
+```ruby
+class MemoryAdapter < PromptManager::Storage::Base
+  def initialize(**options)
+    super
+    @prompts = {}
+    @mutex = Mutex.new
+  end
+  
+  def read(prompt_id)
+    @mutex.synchronize do
+      content = @prompts[prompt_id]
+      raise PromptManager::PromptNotFoundError.new("Prompt '#{prompt_id}' not found") unless content
+      content
+    end
+  end
+  
+  def write(prompt_id, content)
+    @mutex.synchronize do
+      @prompts[prompt_id] = content
+    end
+    true
+  end
+  
+  def exist?(prompt_id)
+    @mutex.synchronize { @prompts.key?(prompt_id) }
+  end
+  
+  def delete(prompt_id)
+    @mutex.synchronize do
+      @prompts.delete(prompt_id) ? true : false
+    end
+  end
+  
+  def list
+    @mutex.synchronize { @prompts.keys }
+  end
+  
+  def clear
+    @mutex.synchronize { @prompts.clear }
+    true
+  end
+end
+```
+
+### Example: HTTPAdapter
+
+```ruby
+require 'net/http'
+require 'json'
+
+class HTTPAdapter < PromptManager::Storage::Base
+  def initialize(base_url:, api_token: nil, **options)
+    super(**options)
+    @base_url = base_url.chomp('/')
+    @api_token = api_token
+  end
+  
+  def read(prompt_id)
+    response = http_get("/prompts/#{prompt_id}")
+    
+    case response.code
+    when '200'
+      JSON.parse(response.body)['content']
+    when '404'
+      raise PromptManager::PromptNotFoundError.new("Prompt '#{prompt_id}' not found")
+    else
+      raise PromptManager::StorageError.new("HTTP error: #{response.code}")
+    end
+  end
+  
+  def write(prompt_id, content)
+    body = { content: content }.to_json
+    response = http_post("/prompts/#{prompt_id}", body)
+    
+    response.code == '200' || response.code == '201'
+  end
+  
+  def exist?(prompt_id)
+    response = http_head("/prompts/#{prompt_id}")
+    response.code == '200'
+  rescue
+    false
+  end
+  
+  def delete(prompt_id)
+    response = http_delete("/prompts/#{prompt_id}")
+    response.code == '200' || response.code == '204'
+  end
+  
+  def list
+    response = http_get("/prompts")
+    return [] unless response.code == '200'
+    
+    JSON.parse(response.body)['prompt_ids']
+  end
+  
+  private
+  
+  def http_get(path)
+    uri = URI("#{@base_url}#{path}")
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    
+    request = Net::HTTP::Get.new(uri)
+    add_auth_header(request)
+    
+    http.request(request)
+  end
+  
+  def http_post(path, body)
+    uri = URI("#{@base_url}#{path}")
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    
+    request = Net::HTTP::Post.new(uri)
+    request['Content-Type'] = 'application/json'
+    request.body = body
+    add_auth_header(request)
+    
+    http.request(request)
+  end
+  
+  def add_auth_header(request)
+    return unless @api_token
+    request['Authorization'] = "Bearer #{@api_token}"
+  end
+end
+```
+
+## Adapter Registration
+
+Register your custom adapter:
+
+```ruby
+# Global configuration
+PromptManager.configure do |config|
+  config.storage = CustomAdapter.new(option: 'value')
+end
+
+# Per-prompt configuration
+prompt = PromptManager::Prompt.new(
+  id: 'special_prompt',
+  storage: CustomAdapter.new
+)
+```
+
+## Error Handling
+
+### Standard Exceptions
+
+All adapters should raise these standard exceptions:
+
+```ruby
+# Prompt not found
+raise PromptManager::PromptNotFoundError.new("Prompt 'xyz' not found")
+
+# Storage operation failed
+raise PromptManager::StorageError.new("Connection timeout")
+
+# Configuration error
+raise PromptManager::ConfigurationError.new("Invalid database URL")
+```
+
+### Error Context
+
+Provide context in error messages:
+
+```ruby
+begin
+  content = storage.read(prompt_id)
+rescue => e
+  raise PromptManager::StorageError.new(
+    "Failed to read prompt '#{prompt_id}': #{e.message}"
+  )
+end
+```
+
+## Performance Considerations
+
+### Connection Pooling
+
+```ruby
+class PooledAdapter < PromptManager::Storage::Base
+  def initialize(pool_size: 10, **options)
+    super(**options)
+    @pool = ConnectionPool.new(size: pool_size) do
+      create_connection
+    end
+  end
+  
+  def read(prompt_id)
+    @pool.with { |conn| conn.read(prompt_id) }
+  end
+end
+```
+
+### Caching
+
+```ruby
+class CachedAdapter < PromptManager::Storage::Base
+  def initialize(cache_ttl: 300, **options)
+    super(**options)
+    @cache = {}
+    @cache_ttl = cache_ttl
+  end
+  
+  def read(prompt_id)
+    cached = @cache[prompt_id]
+    if cached && (Time.current - cached[:timestamp]) < @cache_ttl
+      return cached[:content]
+    end
+    
+    content = super(prompt_id)
+    @cache[prompt_id] = {
+      content: content,
+      timestamp: Time.current
+    }
+    content
+  end
+end
+```
+
+## Testing Adapters
+
+### RSpec Shared Examples
+
+```ruby
+# spec/support/shared_examples/storage_adapter.rb
+RSpec.shared_examples 'a storage adapter' do
+  let(:prompt_id) { 'test_prompt' }
+  let(:content) { 'Hello [NAME]!' }
+  
+  describe '#write and #read' do
+    it 'stores and retrieves content' do
+      expect(adapter.write(prompt_id, content)).to be true
+      expect(adapter.read(prompt_id)).to eq content
+    end
+  end
+  
+  describe '#exist?' do
+    it 'returns false for non-existent prompts' do
+      expect(adapter.exist?('non_existent')).to be false
+    end
+    
+    it 'returns true for existing prompts' do
+      adapter.write(prompt_id, content)
+      expect(adapter.exist?(prompt_id)).to be true
+    end
+  end
+  
+  describe '#delete' do
+    it 'removes prompts' do
+      adapter.write(prompt_id, content)
+      expect(adapter.delete(prompt_id)).to be true
+      expect(adapter.exist?(prompt_id)).to be false
+    end
+  end
+  
+  describe '#list' do
+    it 'returns all prompt IDs' do
+      adapter.write('prompt1', 'content1')
+      adapter.write('prompt2', 'content2')
+      
+      expect(adapter.list).to contain_exactly('prompt1', 'prompt2')
+    end
+  end
+end
+
+# Usage in adapter specs
+describe CustomAdapter do
+  let(:adapter) { described_class.new(options) }
+  
+  include_examples 'a storage adapter'
+end
+```
+
+## Best Practices
+
+1. **Thread Safety**: Ensure adapter operations are thread-safe
+2. **Error Handling**: Use standard PromptManager exceptions
+3. **Resource Management**: Properly close connections and clean up resources
+4. **Configuration Validation**: Validate configuration parameters in constructor
+5. **Documentation**: Document all configuration options and behavior
+6. **Testing**: Use shared examples to ensure consistent behavior
+7. **Performance**: Consider caching and connection pooling for remote storage

data/docs/assets/favicon.ico

@@ -0,0 +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=

data/docs/assets/logo.svg

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background circle -->
+  <circle cx="32" cy="32" r="30" fill="#4F46E5" stroke="#3730A3" stroke-width="2"/>
+  
+  <!-- Librarian figure (simplified) -->
+  <circle cx="32" cy="22" r="6" fill="#F3F4F6"/>
+  <path d="M20 50 Q32 45 44 50" stroke="#F3F4F6" stroke-width="3" fill="none"/>
+  
+  <!-- Floating books -->
+  <rect x="12" y="18" width="8" height="6" rx="1" fill="#FBBF24" transform="rotate(-15 16 21)"/>
+  <rect x="18" y="12" width="8" height="6" rx="1" fill="#EF4444" transform="rotate(25 22 15)"/>
+  <rect x="44" y="16" width="8" height="6" rx="1" fill="#10B981" transform="rotate(15 48 19)"/>
+  <rect x="38" y="10" width="8" height="6" rx="1" fill="#8B5CF6" transform="rotate(-25 42 13)"/>
+  
+  <!-- Golden threads (simplified) -->
+  <path d="M16 21 Q32 28 48 19" stroke="#FBBF24" stroke-width="1" fill="none" opacity="0.6"/>
+  <path d="M22 15 Q32 25 42 13" stroke="#FBBF24" stroke-width="1" fill="none" opacity="0.6"/>
+  
+  <!-- Sparkles -->
+  <circle cx="24" cy="35" r="1" fill="#FBBF24"/>
+  <circle cx="40" cy="33" r="1" fill="#FBBF24"/>
+  <circle cx="28" cy="40" r="1" fill="#FBBF24"/>
+</svg>

data/docs/core-features/comments.md

@@ -0,0 +1,48 @@
+# Comments and Documentation
+
+PromptManager supports comprehensive inline documentation through comments and special sections.
+
+## Line Comments
+
+Lines beginning with `#` are treated as comments and ignored during processing:
+
+```text
+# This is a comment describing the prompt
+# Author: Your Name
+# Version: 1.0
+
+Hello [NAME]! This text will be processed.
+```
+
+## Block Comments
+
+Everything after `__END__` is ignored, creating a documentation section:
+
+```text
+Your prompt content here...
+
+__END__
+This section is completely ignored by PromptManager.
+
+Development notes:
+- TODO: Add more parameters
+- Version history
+- Usage examples
+```
+
+## Documentation Best Practices
+
+```text
+# Description: Customer service greeting template
+# Tags: customer-service, greeting
+# Version: 1.2
+# Author: Support Team
+# Last Updated: 2024-01-15
+
+//include common/header.txt
+
+Your prompt content...
+
+__END__
+Internal notes and documentation go here.
+```

data/docs/core-features/directive-processing.md

@@ -0,0 +1,38 @@
+# Directive Processing
+
+Directives are special instructions in your prompts that begin with `//` and provide powerful prompt composition capabilities.
+
+## Overview
+
+Directives allow you to:
+- Include content from other files
+- Create modular, reusable prompt components
+- Build dynamic prompt structures
+- Process commands during prompt generation
+
+## Built-in Directives
+
+### `//include` (alias: `//import`)
+
+Include content from other files:
+
+```text
+//include common/header.txt
+//import templates/[TEMPLATE_TYPE].txt
+
+Your main prompt content here...
+```
+
+## Example
+
+```text title="customer_response.txt"
+//include common/header.txt
+
+Dear [CUSTOMER_NAME],
+
+Thank you for your inquiry about [TOPIC].
+
+//include common/footer.txt
+```
+
+For detailed examples and advanced usage, see the [Basic Examples](../examples/basic.md).

data/docs/core-features/erb-integration.md

@@ -0,0 +1,68 @@
+# ERB Integration
+
+PromptManager supports ERB (Embedded Ruby) templating for dynamic content generation.
+
+## Enabling ERB
+
+```ruby
+prompt = PromptManager::Prompt.new(
+  id: 'dynamic_prompt',
+  erb_flag: true
+)
+```
+
+## Basic Usage
+
+```text title="dynamic_prompt.txt"
+Current date: <%= Date.today.strftime('%B %d, %Y') %>
+
+<% if '[PRIORITY]' == 'high' %>
+🚨 URGENT: This requires immediate attention!
+<% else %>
+📋 Standard processing request.
+<% end %>
+
+Generated at: <%= Time.now %>
+```
+
+## Advanced Examples
+
+### System Information Template
+
+```text
+**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
+
+<% 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**: <%= `uptime`.strip rescue 'Unable to determine' %>
+```
+
+### Complete Integration Example
+
+See the complete [advanced_integrations.rb](https://github.com/MadBomber/prompt_manager/blob/main/examples/advanced_integrations.rb) example that demonstrates:
+
+- ERB templating with system information
+- Dynamic timestamp generation
+- Platform-specific content rendering
+- Integration with OpenAI API streaming
+- Professional UI with `tty-spinner`
+
+This example shows how to create sophisticated prompts that adapt to your system environment and generate technical analysis reports.
+
+For more comprehensive ERB examples, see the [Examples documentation](../examples.md).