promptly 0.1.13 → 0.1.21

data/lib/promptly.rb

@@ -5,14 +5,68 @@ 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
@@ -43,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.
+```

data/wiki/Quick-Start.md

@@ -0,0 +1,116 @@
+## Quick Start
+
+### 1. Create prompt templates
+
+Create `app/prompts/user_onboarding/welcome_email.en.erb`:
+
+```erb
+You are a friendly customer success manager writing a personalized welcome email.
+
+Context:
+- User name: <%= name %>
+- App name: <%= app_name %>
+- User's role: <%= user_role %>
+- Available features for this user: <%= features.join(", ") %>
+- User signed up <%= days_since_signup %> days ago
+
+Task: Write a warm, personalized welcome email that:
+1. Addresses the user by name
+2. Explains the key benefits specific to their role
+3. Highlights 2-3 most relevant features they should try first
+4. Includes a clear call-to-action to get started
+5. Maintains a professional but friendly tone
+
+Keep the email concise (under 200 words) and actionable.
+```
+
+Create `app/prompts/user_onboarding/welcome_email.es.erb`:
+
+```erb
+Eres un gerente de éxito del cliente amigable escribiendo un email de bienvenida personalizado.
+
+Contexto:
+- Nombre del usuario: <%= name %>
+- Nombre de la app: <%= app_name %>
+- Rol del usuario: <%= user_role %>
+- Funciones disponibles para este usuario: <%= features.join(", ") %>
+- El usuario se registró hace <%= days_since_signup %> días
+
+Tarea: Escribe un email de bienvenida cálido y personalizado que:
+1. Se dirija al usuario por su nombre
+2. Explique los beneficios clave específicos para su rol
+3. Destaque 2-3 funciones más relevantes que debería probar primero
+4. Incluya una llamada a la acción clara para comenzar
+5. Mantenga un tono profesional pero amigable
+
+Mantén el email conciso (menos de 200 palabras) y orientado a la acción.
+```
+
+### 2. Render in your Rails app
+
+```ruby
+# In a controller, service, or anywhere in Rails
+prompt = Promptly.render(
+  "user_onboarding/welcome_email",
+  locale: :es,
+  locals: {
+    name: "María García",
+    app_name: "ProjectHub",
+    user_role: "Team Lead",
+    features: ["Create projects", "Invite team members", "Track progress", "Generate reports"],
+    days_since_signup: 2
+  }
+)
+
+# Send to your AI service (OpenAI, Anthropic, etc.)
+ai_response = openai_client.completions(
+  model: "gpt-4",
+  messages: [{role: "user", content: prompt}]
+)
+
+puts ai_response.dig("choices", 0, "message", "content")
+# => AI-generated personalized welcome email in Spanish
+```
+
+### 3. Test via Rails console
+
+```ruby
+rails console
+
+# Render the prompt before sending to AI
+prompt = Promptly.render(
+  "user_onboarding/welcome_email", 
+  locale: :en, 
+  locals: {
+    name: "John Smith", 
+    app_name: "ProjectHub", 
+    user_role: "Developer",
+    features: ["API access", "Code reviews", "Deployment tools"],
+    days_since_signup: 1
+  }
+)
+puts prompt
+
+# Uses I18n.locale by default
+I18n.locale = :es
+prompt = Promptly.render(
+  "user_onboarding/welcome_email", 
+  locals: {
+    name: "María García", 
+    app_name: "ProjectHub",
+    user_role: "Team Lead",
+    features: ["Crear proyectos", "Invitar miembros", "Seguimiento"],
+    days_since_signup: 3
+  }
+)
+```
+
+### 4. CLI rendering
+
+```bash
+# Render specific locale (shows the prompt, not AI output)
+rails ai_prompts:render[user_onboarding/welcome_email,es]
+
+# Uses default locale
+rails ai_prompts:render[user_onboarding/welcome_email]
+```