promptly 0.1.7 → 0.1.17

data/lib/promptly/tasks/ai_prompts.rake

@@ -22,4 +22,127 @@ namespace :ai_prompts do
       exit 1
     end
   end
+
+  desc "Lint prompt templates. Usage: rake ai_prompts:lint[identifier] LOCALES=en,es REQUIRED=name,app_name PROMPTS_PATH=..."
+  task :lint, [:identifier] => :environment do |_, args|
+    require "erb"
+
+    prompts_path = ENV["PROMPTS_PATH"] || Promptly.prompts_path
+    identifier_filter = args[:identifier]
+
+    locales = if ENV["LOCALES"]
+      ENV["LOCALES"].split(",").map(&:strip).reject(&:empty?)
+    elsif defined?(I18n) && I18n.respond_to?(:available_locales)
+      I18n.available_locales.map(&:to_s)
+    else
+      []
+    end
+
+    required_keys = (ENV["REQUIRED"] || "").split(",").map(&:strip).reject(&:empty?)
+
+    unless File.directory?(prompts_path)
+      warn "[lint] prompts_path not found: #{prompts_path}"
+      exit 1
+    end
+
+    exts = Promptly::Locator::SUPPORTED_EXTS
+
+    files = Dir.glob(File.join(prompts_path, "**", "*{#{exts.join(",")}}"))
+    if identifier_filter
+      files.select! do |f|
+        # match by identifier path without locale/ext
+        rel = f.sub(/^#{Regexp.escape(prompts_path)}\//, "")
+        base = rel.sub(/\.(?:[a-z]{2})?(?:#{exts.map { |e| Regexp.escape(e) }.join("|")})\z/, "")
+        base == identifier_filter
+      end
+    end
+
+    if files.empty?
+      warn "[lint] No templates found under #{prompts_path}#{" for '#{identifier_filter}'" if identifier_filter}"
+      exit 1
+    end
+
+    status = 0
+
+    # Group by identifier (path without locale/ext)
+    grouped = files.group_by do |f|
+      rel = f.sub(/^#{Regexp.escape(prompts_path)}\//, "")
+      rel.sub(/\.(?:[a-z]{2})?(?:#{exts.map { |e| Regexp.escape(e) }.join("|")})\z/, "")
+    end
+
+    grouped.each do |identifier, paths|
+      puts "[lint] Identifier: #{identifier}"
+
+      # 1) Syntax check and placeholder scan per file
+      paths.each do |path|
+        engine = Promptly::Locator.engine_for(path)
+        content = File.read(path)
+
+        begin
+          case engine
+          when :erb
+            # Compile ERB to Ruby, don't execute
+            ERB.new(content)
+          when :liquid
+            if defined?(::Liquid)
+              ::Liquid::Template.parse(content)
+            else
+              warn "  - WARN: Liquid not available; skipping syntax parse for #{File.basename(path)}"
+            end
+          end
+        rescue => e
+          warn "  - ERROR: Syntax error in #{File.basename(path)}: #{e.class}: #{e.message}"
+          status = 1
+        end
+
+        # Required placeholder presence (best-effort scan)
+        if required_keys.any?
+          missing = []
+          required_keys.each do |key|
+            present = false
+            case engine
+            when :erb
+              # naive checks: @key or key inside ERB output tags
+              present ||= content.match?(/<%[=-].*?@#{Regexp.escape(key)}\W/m)
+              present ||= content.match?(/<%[=-].*?\b#{Regexp.escape(key)}\b/m)
+            when :liquid
+              present ||= content.match?(/\{\{\s*#{Regexp.escape(key)}[\s|}]/)
+            end
+            missing << key unless present
+          end
+          if missing.any?
+            warn "  - ERROR: Missing required placeholders in #{File.basename(path)}: #{missing.join(", ")}"
+            status = 1
+          end
+        end
+      end
+
+      # 2) Missing locale files (if locales provided)
+      if locales.any?
+        found_locales = paths.map do |p|
+          # extract locale between name and extension: name.<locale>.ext
+          File.basename(p)[/\.([a-z]{2})\.(?:erb|liquid)\z/, 1]
+        end.compact.uniq
+
+        missing_locales = locales - found_locales
+        if missing_locales.any?
+          warn "  - WARN: Missing locale templates for #{identifier}: #{missing_locales.join(", ")}"
+        else
+          puts "  - OK: Locale coverage satisfied"
+        end
+      end
+    end
+
+    if status.zero?
+      puts "[lint] OK"
+    else
+      warn "[lint] FAIL"
+    end
+    exit status
+  end
+
+  desc "Run functional tests for prompts"
+  task :test_prompts do
+    exec "bundle exec rspec spec/prompts"
+  end
 end

data/lib/promptly/validator.rb

@@ -0,0 +1,24 @@
+module Promptly
+  class Validator
+    def self.validate!(locals, schema_path)
+      return unless File.exist?(schema_path)
+
+      schema = YAML.load_file(schema_path)
+      missing_keys = schema.keys - locals.keys.map(&:to_s)
+      unless missing_keys.empty?
+        raise ArgumentError, "Missing required locals: #{missing_keys.join(", ")}"
+      end
+
+      # Optional: type checking
+      schema.each do |key, type|
+        next unless locals.key?(key.to_sym)
+        value = locals[key.to_sym]
+        case type
+        when "string" then raise TypeError unless value.is_a?(String)
+        when "integer" then raise TypeError unless value.is_a?(Integer)
+        when "array" then raise TypeError unless value.is_a?(Array)
+        end
+      end
+    end
+  end
+end

data/lib/promptly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Promptly
-  VERSION = "0.1.7"
+  VERSION = "0.1.17"
 end

data/lib/promptly.rb

@@ -4,14 +4,69 @@ require_relative "promptly/version"
 require_relative "promptly/renderer"
 require_relative "promptly/locator"
 require_relative "promptly/cache"
+require_relative "promptly/helper"
+require_relative "promptly/validator"
+require "yaml"
 
 module Promptly
   class Error < StandardError; end
+  class ValidationError < Error; end
+
+  class Prompt
+    attr_reader :content, :version, :author, :change_notes
+
+    def initialize(content:, version: nil, author: nil, change_notes: nil)
+      @content = content
+      @version = version
+      @author = author
+      @change_notes = change_notes
+    end
+
+    def to_s
+      content
+    end
+  end
 
   def self.render_template(template, locals: {}, engine: :erb)
     Renderer.render(template, locals: locals, engine: engine)
   end
 
+  def self.response_format(identifier, strict: true)
+    schema_path = File.join(prompts_path, "#{identifier}.response.json")
+    raise Error, "Schema file not found for '#{identifier}' at #{schema_path}" unless File.exist?(schema_path)
+
+    require "json"
+    schema_content = JSON.parse(File.read(schema_path))
+
+    {
+      type: "json_schema",
+      json_schema: {
+        name: identifier.gsub(/[^a-zA-Z0-9_-]/, "_"),
+        strict: strict,
+        schema: schema_content
+      }
+    }
+  end
+
+  def self.validate_response!(identifier, json_string)
+    schema_path = File.join(prompts_path, "#{identifier}.response.json")
+    raise Error, "Schema file not found for '#{identifier}' at #{schema_path}" unless File.exist?(schema_path)
+
+    require "json"
+    require "json_schemer"
+
+    schema_content = JSON.parse(File.read(schema_path))
+    parsed_json = JSON.parse(json_string)
+
+    schemer = JSONSchemer.schema(schema_content)
+    unless schemer.valid?(parsed_json)
+      errors = schemer.validate(parsed_json).to_a
+      raise ValidationError, "Response does not match schema: #{errors.inspect}"
+    end
+
+    parsed_json
+  end
+
   # Configurable prompts root (defaults to Rails.root/app/prompts when Rails is present)
   def self.prompts_path
     @prompts_path || default_prompts_path
@@ -42,12 +97,34 @@ module Promptly
   end
 
   private_class_method def self.render_without_cache(identifier, locale: nil, locals: {})
+    schema_path = File.join(prompts_path, "#{identifier}.schema.yml")
+    Validator.validate!(locals, schema_path)
+
     path = Locator.resolve(identifier, locale: locale)
     raise Error, "Template not found for '#{identifier}' (locale: #{locale.inspect}) under #{prompts_path}" unless path
 
     engine = Locator.engine_for(path)
-    template = File.read(path)
-    Renderer.render(template, locals: locals, engine: engine)
+    file_content = File.read(path)
+
+    # Extract YAML front matter
+    match = file_content.match(/\A---\n(.*)
+---\s*\n/m)
+    if match
+      metadata = YAML.safe_load(match[1])
+      template = match.post_match
+    else
+      metadata = {}
+      template = file_content
+    end
+
+    content = Renderer.render(template, locals: locals, engine: engine)
+
+    Prompt.new(
+      content: content,
+      version: metadata["version"],
+      author: metadata["author"],
+      change_notes: metadata["change_notes"]
+    )
   end
 
   def self.default_prompts_path

data/wiki/Configuration.md

@@ -0,0 +1,63 @@
+## Configuration
+
+### Custom Prompts Path
+
+```ruby
+# config/initializers/rails_ai_prompts.rb
+Promptly.prompts_path = Rails.root.join("lib", "ai_prompts")
+```
+
+### Caching
+
+Promptly supports optional caching for rendered prompts.
+
+- Default: enabled, TTL = 3600 seconds (1 hour).
+- In Rails, the Railtie auto-uses `Rails.cache` if present.
+
+Configure globally:
+
+```ruby
+# config/initializers/promptly.rb
+Promptly::Cache.configure do |c|
+  c.store = Rails.cache # or any ActiveSupport::Cache store
+  c.ttl = 3600          # default TTL in seconds
+  c.enabled = true      # globally enable/disable caching
+end
+```
+
+Per-call options:
+
+```ruby
+# Bypass cache for this render only
+Promptly.render("user_onboarding/welcome_email", locals: {...}, cache: false)
+
+# Custom TTL for this render only
+Promptly.render("user_onboarding/welcome_email", locals: {...}, ttl: 5.minutes)
+```
+
+Invalidation:
+
+```ruby
+# Clear entire cache store (if supported by the store)
+Promptly::Cache.clear
+
+# Delete a specific cached entry
+Promptly::Cache.delete(
+  identifier: "user_onboarding/welcome_email",
+  locale: :en,
+  locals: {name: "John"},
+  prompts_path: Promptly.prompts_path
+)
+```
+
+### Direct Template Rendering
+
+```ruby
+# Render ERB directly (without file lookup)
+template = "Hello <%= name %>, welcome to <%= app %>!"
+output = Promptly.render_template(template, locals: {name: "John", app: "MyApp"})
+
+# Render Liquid directly
+template = "Hello {{ name }}, welcome to {{ app }}!"
+output = Promptly.render_template(template, locals: {name: "John", app: "MyApp"}, engine: :liquid)
+```

data/wiki/Functional-Prompt-Tests.md

@@ -0,0 +1,36 @@
+## Functional Prompt Tests
+
+Promptly provides an RSpec helper to write functional tests for your prompts. This allows you to verify the rendered output of your prompts, ensuring that they are correctly formatted and that all variables are properly interpolated.
+
+### RSpec Helper
+
+The `expect_prompt_render` helper is available in your RSpec tests. It takes the prompt identifier and a hash of locals as arguments.
+
+**Example:**
+
+```ruby
+# spec/prompts/user_onboarding/welcome_email_spec.rb
+require "spec_helper"
+
+RSpec.describe "user_onboarding/welcome_email" do
+  it "renders the welcome email correctly" do
+    locals = {
+      name: "John Doe",
+      app_name: "My App",
+      user_role: "Admin",
+      features: ["Feature 1", "Feature 2"],
+      days_since_signup: 5
+    }
+
+    expect(Promptly.render("user_onboarding/welcome_email", locals: locals)).to include("Hello John Doe")
+  end
+end
+```
+
+### Rake Task
+
+You can run all your prompt tests using the `ai_prompts:test_prompts` Rake task.
+
+```bash
+rake ai_prompts:test_prompts
+```

data/wiki/Generators.md

@@ -0,0 +1,32 @@
+## Generators
+
+Create prompt templates following conventions.
+
+```bash
+# ERB with multiple locales
+rails g promptly:prompt user_onboarding/welcome_email --locales en es --engine erb
+
+# Liquid with a single locale
+rails g promptly:prompt ai_coaching/goal_review --locales en --engine liquid
+
+# Fallback-only (no locale suffix)
+rails g promptly:prompt content_generation/outline --no-locale
+```
+
+Options:
+
+- `--engine` erb|liquid (default: erb)
+- `--locales` space-separated list (default: I18n.available_locales if available, else `en`)
+- `--no-locale` create only fallback file (e.g., `welcome_email.erb`)
+- `--force` overwrite existing files
+
+Generated files are placed under `app/prompts/` and directories are created as needed.
+
+Examples:
+
+- `app/prompts/user_onboarding/welcome_email.en.erb`
+- `app/prompts/user_onboarding/welcome_email.es.erb`
+- `app/prompts/ai_coaching/goal_review.en.liquid`
+- `app/prompts/content_generation/outline.erb` (fallback-only)
+
+The generator seeds a minimal, intention-revealing scaffold you can edit immediately.

data/wiki/Helper-render_prompt.md

@@ -0,0 +1,25 @@
+## Helper: render_prompt
+
+Use a concise helper anywhere in Rails to render prompts with locals that are also exposed as instance variables inside ERB templates.
+
+* **Auto-included**: Controllers, Mailers, and Jobs via Railtie.
+* **Services/Plain Ruby**: `include Promptly::Helper`.
+
+Example template and usage:
+
+```erb
+# app/prompts/welcome_email.erb
+Hello <%= @user.name %>, welcome to our service!
+We're excited to have you join.
+```
+
+```ruby
+# In a mailer, job, controller, or a service that includes Promptly::Helper
+rendered = render_prompt("welcome_email", user: @user)
+```
+
+Notes:
+
+- **Locals become @instance variables** in ERB. Passing `user: @user` makes `@user` available in the template.
+- **Localization**: `render_prompt("welcome_email", locale: :es, user: user)` resolves `welcome_email.es.erb` with fallback per `Promptly::Locator`.
+- **Caching**: Controlled per call (`cache:`, `ttl:`) and globally via `Promptly::Cache`.

data/wiki/Home.md

@@ -0,0 +1,29 @@
+# Welcome to the Promptly Wiki!
+
+Promptly is an opinionated Rails integration for reusable AI prompt templates. It helps you build maintainable, localized, and testable AI prompts using ERB or Liquid templates with Rails conventions.
+
+This wiki provides detailed documentation for Promptly. If you are new to Promptly, we recommend starting with the [Quick Start](https://github.com/wilburhimself/promptly/wiki/Quick-Start) guide.
+
+## Features
+
+- **Template rendering**: ERB (via ActionView) and optional Liquid support
+- **I18n integration**: Automatic locale fallback (`welcome.es.erb` → `welcome.en.erb` → `welcome.erb`)
+- **Rails conventions**: Store prompts in `app/prompts/` with organized subdirectories
+- **Render & CLI**: Test prompts in Rails console or via rake tasks
+- **Minimal setup**: Auto-loads via Railtie, zero configuration required
+- **Prompt caching**: Configurable cache store, TTL, and cache-bypass options
+- **Schema Validation**: Ensure all locals passed to templates match a defined schema.
+- **Functional Prompt Tests**: Write functional tests for your prompts using RSpec.
+
+## Documentation
+
+- [Quick Start](https://github.com/wilburhimself/promptly/wiki/Quick-Start)
+- [Schema Validation](https://github.com/wilburhimself/promptly/wiki/Schema-Validation)
+- [Helper: render_prompt](https://github.com/wilburhimself/promptly/wiki/Helper-render_prompt)
+- [Rails App Integration](https://github.com/wilburhimself/promptly/wiki/Rails-App-Integration)
+- [I18n Prompts Usage](https://github.com/wilburhimself/promptly/wiki/I18n-Prompts-Usage)
+- [Liquid Templates](https://github.com/wilburhimself/promptly/wiki/Liquid-Templates)
+- [Configuration](https://github.com/wilburhimself/promptly/wiki/Configuration)
+- [Generators](https://github.com/wilburhimself/promptly/wiki/Generators)
+- [Linting Templates](https://github.com/wilburhimself/promptly/wiki/Linting-Templates)
+- [Functional Prompt Tests](https://github.com/wilburhimself/promptly/wiki/Functional-Prompt-Tests)

data/wiki/I18n-Prompts-Usage.md

@@ -0,0 +1,60 @@
+## I18n Prompts Usage
+
+### Directory Structure
+
+```
+app/prompts/
+├── user_onboarding/
+│   ├── welcome_email.en.erb          # English AI prompt
+│   ├── welcome_email.es.erb          # Spanish AI prompt
+│   └── onboarding_checklist.erb      # Fallback (any locale)
+├── content_generation/
+│   ├── blog_post_outline.en.erb
+│   ├── social_media_post.es.erb
+│   └── product_description.erb
+└── ai_coaching/
+    ├── goal_review.en.liquid          # Liquid AI prompt
+    └── goal_review.es.liquid
+```
+
+### Locale Resolution
+
+Promptly follows this resolution order:
+
+1. **Requested locale**: `welcome.es.erb` (if `locale: :es` specified)
+2. **Default locale**: `welcome.en.erb` (if `I18n.default_locale == :en`)
+3. **Fallback**: `welcome.erb` (no locale suffix)
+
+```ruby
+# Configure I18n in your Rails app
+# config/application.rb
+config.i18n.default_locale = :en
+config.i18n.available_locales = [:en, :es, :fr]
+
+# Usage examples
+I18n.locale = :es
+I18n.default_locale = :en
+
+# Will try: welcome_email.es.erb → welcome_email.en.erb → welcome_email.erb
+prompt = Promptly.render(
+  "user_onboarding/welcome_email", 
+  locals: {
+    name: "María García",
+    app_name: "ProjectHub",
+    user_role: "Manager",
+    features: ["Team management", "Analytics", "Reporting"],
+    days_since_signup: 1
+  }
+)
+
+# Force specific locale for AI prompt generation
+prompt = Promptly.render(
+  "content_generation/blog_post_outline", 
+  locale: :fr, 
+  locals: {
+    topic: "Intelligence Artificielle",
+    target_audience: "Développeurs",
+    word_count: 1500
+  }
+)
+```

data/wiki/Linting-Templates.md

@@ -0,0 +1,38 @@
+## Linting Templates
+
+Validate your prompt templates from the CLI.
+
+```bash
+# Lint all templates under the prompts path
+rake ai_prompts:lint
+
+# Lint a specific identifier (path without locale/ext)
+rake ai_prompts:lint[user_onboarding/welcome_email]
+
+# Specify locales to check for coverage
+LOCALES=en,es rake ai_prompts:lint
+
+# Require placeholders to exist in templates
+REQUIRED=name,app_name rake ai_prompts:lint[user_onboarding/welcome_email]
+
+# Point to a custom prompts directory
+PROMPTS_PATH=lib/ai_prompts rake ai_prompts:lint
+```
+
+What it checks:
+
+- **Syntax errors**
+  - ERB: compiles with `ERB.new` (no execution)
+  - Liquid: parses with `Liquid::Template.parse` (if `liquid` gem present)
+- **Missing locale files**
+  - For each identifier, warns when required locales are missing
+  - Locales source: `LOCALES` env or `I18n.available_locales`
+- **Required placeholders**
+  - Best-effort scan for required keys from `REQUIRED` env
+  - ERB: looks for `<%= ... @key ... %>` or `<%= ... key ... %>` usage
+  - Liquid: looks for `{{ key }}` usage
+
+Exit codes:
+
+- `0` when all checks pass
+- `1` when errors are found (syntax or missing required placeholders)

data/wiki/Liquid-Templates.md

@@ -0,0 +1,49 @@
+### Liquid Templates
+
+For more complex templating needs, use Liquid:
+
+```liquid
+<!-- app/prompts/ai_coaching/goal_review.en.liquid -->
+You are an experienced life coach conducting a goal review session.
+
+Context:
+- Client name: {{ user_name }}
+- Goals being reviewed: {% for goal in current_goals %}{{ goal }}{% unless forloop.last %}, {% endunless %}{% endfor %}
+- Recent progress: {{ progress_summary }}
+- Current challenges: {% for challenge in challenges %}{{ challenge }}{% unless forloop.last %}, {% endunless %}{% endfor %}
+- Review period: {{ review_period | default: "monthly" }}
+
+Task: Provide a personalized goal review that:
+1. Acknowledges their progress and celebrates wins
+2. Addresses each challenge with specific, actionable advice
+3. Suggests 2-3 concrete next steps for the coming {{ review_period }}
+4. Asks 1-2 thoughtful questions to help them reflect
+5. Maintains an encouraging but realistic tone
+
+{% if current_goals.size > 5 %}
+Note: The client has many goals. Help them prioritize the most important ones.
+{% endif %}
+
+Format your response as a conversational coaching session, not a formal report.
+```
+
+```ruby
+# Generate AI coaching content with Liquid template
+prompt = Promptly.render(
+  "ai_coaching/goal_review",
+  locale: :en,
+  locals: {
+    user_name: "Alex",
+    current_goals: ["Run 5K under 25min", "Gym 3x/week", "Read 12 books/year"],
+    progress_summary: "Consistent with gym, behind on running pace, ahead on reading",
+    challenges: ["Time management", "Motivation on rainy days"],
+    review_period: "monthly"
+  }
+)
+
+# Send to AI service for personalized coaching
+ai_coaching_session = openai_client.chat(
+  model: "gpt-4",
+  messages: [{role: "user", content: prompt}]
+).dig("choices", 0, "message", "content")
+```

data/wiki/Prompt-Version-Metadata.md

@@ -0,0 +1,34 @@
+## Prompt Version Metadata
+
+Promptly allows you to add optional metadata fields to your prompt templates, such as `version`, `author`, and `change_notes`. This metadata can be useful for tracking changes to your prompts and for documentation purposes.
+
+### Adding Metadata to Prompts
+
+To add metadata to a prompt, include a YAML front matter block at the beginning of your template file. The front matter block must start and end with `---`.
+
+**Example:**
+
+```erb
+---
+version: 1.0
+author: John Doe
+change_notes: Initial version of the welcome email.
+---
+You are a friendly customer success manager writing a personalized welcome email.
+...
+```
+
+### Accessing Metadata
+
+When you render a prompt, the `Promptly.render` method returns a `Prompt` object. This object contains the rendered content of the prompt, as well as the metadata fields.
+
+**Example:**
+
+```ruby
+prompt = Promptly.render("user_onboarding/welcome_email")
+
+puts prompt.content        # The rendered content of the email
+puts prompt.version        # 1.0
+puts prompt.author         # John Doe
+puts prompt.change_notes   # Initial version of the welcome email.
+```