prompt_manager 0.5.7 → 0.5.8

data/docs/getting-started/installation.md

@@ -0,0 +1,97 @@
+# Installation
+
+## System Requirements
+
+PromptManager requires:
+
+- **Ruby**: 2.7 or higher (3.0+ recommended)
+- **Operating System**: Linux, macOS, or Windows
+- **Dependencies**: No additional system dependencies required
+
+## Install the Gem
+
+### Using Bundler (Recommended)
+
+Add PromptManager to your project's `Gemfile`:
+
+```ruby
+# Gemfile
+gem 'prompt_manager'
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+### Using RubyGems
+
+Install directly with gem:
+
+```bash
+gem install prompt_manager
+```
+
+### Development Installation
+
+For development or to get the latest features:
+
+```bash
+git clone https://github.com/MadBomber/prompt_manager.git
+cd prompt_manager
+bundle install
+```
+
+## Verify Installation
+
+Test that PromptManager is installed correctly:
+
+```ruby
+require 'prompt_manager'
+puts PromptManager::VERSION
+```
+
+## Dependencies
+
+PromptManager has minimal dependencies and automatically installs:
+
+- **No external system dependencies**
+- **Pure Ruby dependencies** only
+- **Lightweight footprint** for easy integration
+
+## Troubleshooting
+
+### Common Issues
+
+!!! warning "Ruby Version"
+    
+    If you see compatibility errors, ensure you're running Ruby 2.7+:
+    
+    ```bash
+    ruby --version
+    ```
+
+!!! tip "Bundler Issues"
+    
+    If bundle install fails, try updating bundler:
+    
+    ```bash
+    gem update bundler
+    bundle install
+    ```
+
+### Getting Help
+
+If you encounter installation issues:
+
+1. Check the [GitHub Issues](https://github.com/MadBomber/prompt_manager/issues)
+2. Search for similar problems in [Discussions](https://github.com/MadBomber/prompt_manager/discussions)  
+3. Create a new issue with:
+   - Ruby version (`ruby --version`)
+   - Gem version (`gem list prompt_manager`)
+   - Error message and full stack trace
+
+## Next Steps
+
+Once installed, continue to the [Quick Start](quick-start.md) guide to begin using PromptManager.

data/docs/getting-started/quick-start.md

@@ -0,0 +1,256 @@
+# Quick Start
+
+This guide will get you up and running with PromptManager in just a few minutes.
+
+## 1. Install PromptManager
+
+```bash
+gem install prompt_manager
+```
+
+## 2. Set Up Your First Prompt
+
+Create a directory for your prompts and your first prompt file:
+
+```bash
+mkdir ~/.prompts
+```
+
+Create your first prompt file:
+
+=== "~/.prompts/greeting.txt"
+
+    ```text
+    # Description: A friendly greeting prompt
+    # Keywords: NAME, LANGUAGE
+    
+    Hello [NAME]! 
+    
+    I'm here to help you today. Please let me know how I can assist you,
+    and I'll respond in [LANGUAGE].
+    
+    What would you like to know about?
+    ```
+
+=== "~/.prompts/greeting.json"
+
+    ```json
+    {
+      "[NAME]": ["Alice", "Bob", "Charlie"],
+      "[LANGUAGE]": ["English", "Spanish", "French"]
+    }
+    ```
+
+## 3. Basic Usage
+
+Create a simple Ruby script to use your prompt:
+
+```ruby title="quick_example.rb"
+#!/usr/bin/env ruby
+
+require 'prompt_manager'
+
+# Configure the FileSystem storage adapter
+PromptManager::Prompt.storage_adapter = 
+  PromptManager::Storage::FileSystemAdapter.config do |config|
+    config.prompts_dir = File.expand_path('~/.prompts')
+  end.new
+
+# Load your prompt
+prompt = PromptManager::Prompt.new(id: 'greeting')
+
+# Set parameter values
+prompt.parameters = {
+  "[NAME]" => "Alice",
+  "[LANGUAGE]" => "English"
+}
+
+# Generate the final prompt text
+puts "=== Generated Prompt ==="
+puts prompt.to_s
+
+# Save any parameter changes
+prompt.save
+```
+
+Run it:
+
+```bash
+ruby quick_example.rb
+```
+
+Expected output:
+```
+=== Generated Prompt ===
+Hello Alice! 
+
+I'm here to help you today. Please let me know how I can assist you,
+and I'll respond in English.
+
+What would you like to know about?
+```
+
+## 4. Understanding the Workflow
+
+The basic PromptManager workflow involves:
+
+```mermaid
+graph LR
+    A[Create Prompt File] --> B[Configure Storage]
+    B --> C[Load Prompt]
+    C --> D[Set Parameters]
+    D --> E[Generate Text]
+    E --> F[Save Changes]
+```
+
+### Step by Step:
+
+1. **Create Prompt File**: Write your template with `[KEYWORDS]`
+2. **Configure Storage**: Choose FileSystem or ActiveRecord adapter
+3. **Load Prompt**: Create a Prompt instance with an ID
+4. **Set Parameters**: Provide values for your keywords
+5. **Generate Text**: Call `to_s` to get the final prompt
+6. **Save Changes**: Persist parameter updates
+
+## 5. Advanced Quick Start
+
+Here's a more advanced example showing multiple features:
+
+```ruby title="advanced_example.rb"
+require 'prompt_manager'
+
+# Configure storage
+PromptManager::Prompt.storage_adapter = 
+  PromptManager::Storage::FileSystemAdapter.config do |config|
+    config.prompts_dir = File.expand_path('~/.prompts')
+  end.new
+
+# Create a prompt with directives and ERB
+prompt = PromptManager::Prompt.new(
+  id: 'advanced_greeting',
+  erb_flag: true,
+  envar_flag: true
+)
+
+# Set parameters
+prompt.parameters = {
+  "[USER_NAME]" => "Alice",
+  "[TASK_TYPE]" => "translation",
+  "[URGENCY]" => "high"
+}
+
+# Display available keywords
+puts "Available keywords: #{prompt.keywords.join(', ')}"
+
+# Generate and display the result
+puts "\n=== Final Prompt ==="
+puts prompt.to_s
+
+# Save changes
+prompt.save
+puts "\nPrompt saved successfully!"
+```
+
+=== "~/.prompts/advanced_greeting.txt"
+
+    ```text
+    # Advanced greeting with directives and ERB
+    //include common/header.txt
+    
+    Dear [USER_NAME],
+    
+    <% if '[URGENCY]' == 'high' %>
+    🚨 URGENT: This [TASK_TYPE] request requires immediate attention.
+    <% else %>
+    📋 Standard [TASK_TYPE] request for processing.
+    <% end %>
+    
+    Current system time: <%= Time.now.strftime('%Y-%m-%d %H:%M:%S') %>
+    Working directory: <%= Dir.pwd %>
+    
+    __END__
+    This section is ignored - useful for notes and documentation.
+    ```
+
+## 6. Next Steps
+
+Now that you have PromptManager working, explore these areas:
+
+### Learn Core Features
+- [Parameterized Prompts](../core-features/parameterized-prompts.md) - Master keyword substitution
+- [Directive Processing](../core-features/directive-processing.md) - Include files and process commands
+- [ERB Integration](../core-features/erb-integration.md) - Dynamic templating
+
+### Storage Options  
+- [FileSystem Adapter](../storage/filesystem-adapter.md) - File-based storage
+- [ActiveRecord Adapter](../storage/activerecord-adapter.md) - Database storage
+- [Custom Adapters](../storage/custom-adapters.md) - Build your own
+
+### Advanced Usage
+- [Custom Keywords](../advanced/custom-keywords.md) - Define your own keyword patterns
+- [Search Integration](../advanced/search-integration.md) - Find prompts quickly
+- [Performance Tips](../advanced/performance.md) - Optimize for large collections
+
+### Real Examples
+- [Basic Examples](../examples/basic.md) - Simple use cases
+- [Advanced Examples](../examples/advanced.md) - Complex scenarios
+- [Real World Cases](../examples/real-world.md) - Production examples
+
+## Common Patterns
+
+Here are some common patterns you'll use frequently:
+
+### Parameter History
+```ruby
+# Access parameter history (since v0.3.0)
+prompt.parameters["[NAME]"]  # Returns ["Alice", "Bob", "Charlie"] 
+latest_name = prompt.parameters["[NAME]"].last  # "Charlie"
+```
+
+### Error Handling
+```ruby
+begin
+  prompt = PromptManager::Prompt.new(id: 'missing')
+rescue PromptManager::StorageError => e
+  puts "Storage error: #{e.message}"
+rescue PromptManager::ParameterError => e
+  puts "Parameter error: #{e.message}"
+end
+```
+
+### Search and Discovery
+```ruby
+# List all available prompts
+prompts = PromptManager::Prompt.list
+puts "Available prompts: #{prompts.join(', ')}"
+
+# Search for prompts (requires search_proc configuration)
+results = PromptManager::Prompt.search('greeting')
+```
+
+## Troubleshooting
+
+### File Not Found
+If you get "file not found" errors, check:
+
+1. **Prompt directory exists**: `ls ~/.prompts`
+2. **File has correct extension**: Should be `.txt` by default
+3. **Prompt ID matches filename**: `greeting` looks for `greeting.txt`
+
+### Parameter Errors
+If parameters aren't substituting:
+
+1. **Check keyword format**: Must be `[UPPERCASE]` by default
+2. **Verify parameter keys match**: Case-sensitive matching
+3. **Ensure parameters are set**: Call `prompt.parameters = {...}`
+
+### Permission Issues
+If you can't write to the prompts directory:
+
+```bash
+chmod 755 ~/.prompts
+chmod 644 ~/.prompts/*.txt
+chmod 644 ~/.prompts/*.json
+```
+
+Need help? Check our [testing guide](../development/testing.md) or [open an issue](https://github.com/MadBomber/prompt_manager/issues).

data/docs/index.md

@@ -0,0 +1,230 @@
+# PromptManager Documentation
+
+<div align="center" style="background-color: #fff3cd; color: #856404; padding: 20px; margin: 20px 0; border: 2px solid #ffeaa7; border-radius: 5px; font-size: 18px; font-weight: bold;">
+  ⚠️ CAUTION ⚠️<br />
+  Breaking Changes are Coming<br />
+  See <a href="development/roadmap/">Roadmap</a> for details
+</div>
+
+<div align="center">
+  <table>
+    <tr>
+      <td width="40%" align="center" valign="top">
+        <img src="../prompt_manager_logo.png" alt="PromptManager - The Enchanted Librarian of AI Prompts" width="400">
+      </td>
+      <td width="60%" align="left" valign="top">
+        <p><strong>Like an enchanted librarian organizing floating books of knowledge, PromptManager helps you masterfully orchestrate and organize your AI prompts through wisdom and experience.</strong></p>
+        
+        <p>Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships.</p>
+        
+        <h3>Key Features</h3>
+        <ul>
+            <li><strong>📚 <a href="storage/overview/">Multiple Storage Adapters</a></strong></li>
+            <li><strong>🔧 <a href="core-features/parameterized-prompts/">Parameterized Prompts</a></strong></li>
+            <li><strong>📋 <a href="core-features/directive-processing/">Directive Processing</a></strong></li>
+            <li><strong>🎨 <a href="core-features/erb-integration/">ERB Integration</a></strong></li>
+            <li><strong>🌍 <a href="core-features/shell-integration/">Shell Integration</a></strong></li>
+            <li><strong>📖 <a href="core-features/comments/">Inline Documentation</a></strong></li>
+            <li><strong>📊 <a href="core-features/parameter-history/">Parameter History</a></strong></li>
+            <li><strong>⚡ <a href="core-features/error-handling/">Error Handling</a></strong></li>
+            <li><strong>🔌 <a href="advanced/custom-keywords/">Extensible Architecture</a></strong></li>
+        </ul>
+      </td>
+    </tr>
+  </table>
+</div>
+
+## What is PromptManager?
+
+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.
+
+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.
+
+## Quick Start
+
+Get up and running with PromptManager in minutes:
+
+=== "Installation"
+
+    ```bash
+    gem install prompt_manager
+    # or add to Gemfile
+    bundle add prompt_manager
+    ```
+
+=== "Basic Usage"
+
+    ```ruby
+    require 'prompt_manager'
+
+    # Configure storage
+    PromptManager::Prompt.storage_adapter = 
+      PromptManager::Storage::FileSystemAdapter.config do |config|
+        config.prompts_dir = '~/.prompts'
+      end.new
+
+    # Use a prompt
+    prompt = PromptManager::Prompt.new(id: 'greeting')
+    prompt.parameters = {
+      "[NAME]" => "Alice",
+      "[LANGUAGE]" => "English"
+    }
+    
+    puts prompt.to_s
+    ```
+
+=== "Create a Prompt"
+
+    ```text
+    # ~/.prompts/greeting.txt
+    # Description: A friendly greeting prompt
+    
+    Hello [NAME]! How can I assist you today?
+    Please respond in [LANGUAGE].
+    ```
+
+## Architecture Overview
+
+PromptManager follows a modular architecture designed for flexibility and extensibility:
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        A[Your Application]
+        P[PromptManager::Prompt]
+    end
+    
+    subgraph "Processing Layer"
+        D[Directive Processor]
+        E[ERB Engine]
+        K[Keyword Substitution]
+    end
+    
+    subgraph "Storage Layer"
+        FS[FileSystem Adapter]
+        AR[ActiveRecord Adapter]
+        CA[Custom Adapter]
+    end
+    
+    A --> P
+    P --> D
+    P --> E
+    P --> K
+    P --> FS
+    P --> AR
+    P --> CA
+    
+    D --> |includes| FS
+    E --> |templates| P
+    K --> |substitutes| P
+```
+
+## Core Concepts
+
+### Parameterized Prompts
+
+Transform static prompts into dynamic templates:
+
+```ruby
+# Template with parameters
+prompt_text = "Translate '[TEXT]' from [SOURCE_LANG] to [TARGET_LANG]"
+
+# Filled with values
+prompt.parameters = {
+  "[TEXT]" => "Hello world",
+  "[SOURCE_LANG]" => "English", 
+  "[TARGET_LANG]" => "Spanish"
+}
+
+# Result: "Translate 'Hello world' from English to Spanish"
+```
+
+### Directive Processing
+
+Use JCL-style directives for prompt composition:
+
+```text
+# Common header for all customer service prompts
+//include common/customer_service_header.txt
+
+# Dynamic template inclusion
+//include templates/[TEMPLATE_TYPE].txt
+
+Handle this customer inquiry about [TOPIC].
+```
+
+### Storage Adapters
+
+Choose your preferred storage backend:
+
+- **FileSystemAdapter**: Store prompts as text files
+- **ActiveRecordAdapter**: Store prompts in a database  
+- **Custom Adapters**: Build your own storage solution
+
+## Why PromptManager?
+
+### 🎯 **Organized Prompts**
+Keep your prompts organized in a structured, searchable format instead of scattered across your codebase.
+
+### 🔄 **Reusable Templates** 
+Create parameterized templates that can be reused across different contexts and applications.
+
+### 🛠️ **Powerful Processing**
+Advanced features like directive processing, ERB templating, and environment variable substitution.
+
+### 📈 **Scalable Architecture**
+Modular design supports everything from simple scripts to enterprise applications.
+
+### 🔍 **Easy Management**
+Built-in search capabilities and parameter history make prompt management effortless.
+
+## Getting Started
+
+Ready to dive in? Here are some great places to start:
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-rocket:{ .lg .middle } __Quick Start__
+
+    ---
+
+    Get PromptManager running in your project within minutes
+    
+    [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md)
+
+-   :fontawesome-solid-book:{ .lg .middle } __Core Features__
+
+    ---
+
+    Learn about parameterized prompts, directives, and more
+    
+    [:octicons-arrow-right-24: Core Features](core-features/parameterized-prompts.md)
+
+-   :fontawesome-solid-database:{ .lg .middle } __Storage Adapters__
+
+    ---
+
+    Choose the right storage solution for your needs
+    
+    [:octicons-arrow-right-24: Storage Options](storage/overview.md)
+
+-   :fontawesome-solid-code:{ .lg .middle } __API Reference__
+
+    ---
+
+    Complete reference for all classes and methods
+    
+    [:octicons-arrow-right-24: API Docs](api/prompt-class.md)
+
+</div>
+
+## Community & Support
+
+- **GitHub**: [MadBomber/prompt_manager](https://github.com/MadBomber/prompt_manager)
+- **RubyGems**: [prompt_manager](https://rubygems.org/gems/prompt_manager)
+- **Issues**: [Report bugs or request features](https://github.com/MadBomber/prompt_manager/issues)
+- **Discussions**: [Community discussions](https://github.com/MadBomber/prompt_manager/discussions)
+
+## License
+
+PromptManager is released under the [MIT License](https://opensource.org/licenses/MIT).