promptly 0.1.2 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23c7ae8e3735bb7596001fa52d79a218068be2f0c03ddbb1a5fb8aa263035489
-  data.tar.gz: a44b67aa11f2ca04c26c6b291369d4f6c7c9044c5bd61ed8cfc921b01afd9df5
+  metadata.gz: acd140832db9c4f719f094548791c956ec3cb0f7380cf1c213e9923be1070fe2
+  data.tar.gz: abdba3ecdc1c1d4a03f012944c5ebc08d906c02266872eb9e3fb54483add5f55
 SHA512:
-  metadata.gz: 382205e203447a670cb437b0a04a8ad42d137fe887d5690afe50bc3402f13be5b1ec0395e7d9450420aa60d7ae194283b3211dd1a417f620555733d2bb6d0859
-  data.tar.gz: 90b523fa6fa36447e72e4dfda79c500510448bd9f4ed1a9353b30bae7b024d8a13b4d753cdb522f56bdab59dcea40d0be532b7fd8afdc51c5caf6abe66cdba4a
+  metadata.gz: b714d8ec43e3491248fc5a229cbbc2018227a28b32b68d84e8961fab5fe5185b860c55de425f3c573eb9b776f1922b5e56b331a6cf2be95cf7d8f33b303f8d1a
+  data.tar.gz: 69afcef9ff51ba00326a5e1efa1226777aecc97cfc9f9d85998a960353758a05b1fa967cef716dd441618f68afe67194333c0f4c1253a1b773d3f2818930dd12

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/README.md

@@ -1,3 +1,4 @@
+
 # Promptly
 
 Opinionated Rails integration for reusable AI prompt templates. Build maintainable, localized, and testable AI prompts using ERB or Liquid templates with Rails conventions.
@@ -7,8 +8,9 @@ Opinionated Rails integration for reusable AI prompt templates. Build maintainab
 - **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
-- **Preview & CLI**: Test prompts in Rails console or via rake tasks
+- **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
 
 ## Install
 
@@ -82,7 +84,7 @@ Mantén el email conciso (menos de 200 palabras) y orientado a la acción.
 
 ```ruby
 # In a controller, service, or anywhere in Rails
-prompt = Promptly.preview(
+prompt = Promptly.render(
   "user_onboarding/welcome_email",
   locale: :es,
   locals: {
@@ -109,8 +111,8 @@ puts ai_response.dig("choices", 0, "message", "content")
 ```ruby
 rails console
 
-# Preview the prompt before sending to AI
-prompt = Promptly.preview(
+# Render the prompt before sending to AI
+prompt = Promptly.render(
   "user_onboarding/welcome_email", 
   locale: :en, 
   locals: {
@@ -125,7 +127,7 @@ puts prompt
 
 # Uses I18n.locale by default
 I18n.locale = :es
-prompt = Promptly.preview(
+prompt = Promptly.render(
   "user_onboarding/welcome_email", 
   locals: {
     name: "María García", 
@@ -137,16 +139,42 @@ prompt = Promptly.preview(
 )
 ```
 
-### 4. CLI preview
+### 4. CLI rendering
 
 ```bash
-# Preview specific locale (shows the prompt, not AI output)
-rails ai_prompts:preview[user_onboarding/welcome_email,es]
+# Render specific locale (shows the prompt, not AI output)
+rails ai_prompts:render[user_onboarding/welcome_email,es]
 
 # Uses default locale
-rails ai_prompts:preview[user_onboarding/welcome_email]
+rails ai_prompts:render[user_onboarding/welcome_email]
+```
+
+## 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`.
+
 ## Rails App Integration
 
 ### Service Object Pattern
@@ -155,7 +183,7 @@ rails ai_prompts:preview[user_onboarding/welcome_email]
 # app/services/ai_prompt_service.rb
 class AiPromptService
   def self.generate_welcome_email(user, locale: I18n.locale)
-    prompt = Promptly.preview(
+    prompt = Promptly.render(
       "user_onboarding/welcome_email",
       locale: locale,
       locals: {
@@ -219,7 +247,7 @@ class GenerateAiContentJob < ApplicationJob
   def perform(user_id, prompt_identifier, locals = {})
     user = User.find(user_id)
     
-    prompt = Promptly.preview(
+    prompt = Promptly.render(
       prompt_identifier,
       locale: user.locale,
       locals: locals.merge(
@@ -302,7 +330,7 @@ I18n.locale = :es
 I18n.default_locale = :en
 
 # Will try: welcome_email.es.erb → welcome_email.en.erb → welcome_email.erb
-prompt = Promptly.preview(
+prompt = Promptly.render(
   "user_onboarding/welcome_email", 
   locals: {
     name: "María García",
@@ -314,7 +342,7 @@ prompt = Promptly.preview(
 )
 
 # Force specific locale for AI prompt generation
-prompt = Promptly.preview(
+prompt = Promptly.render(
   "content_generation/blog_post_outline", 
   locale: :fr, 
   locals: {
@@ -356,7 +384,7 @@ Format your response as a conversational coaching session, not a formal report.
 
 ```ruby
 # Generate AI coaching content with Liquid template
-prompt = Promptly.preview(
+prompt = Promptly.render(
   "ai_coaching/goal_review",
   locale: :en,
   locals: {
@@ -384,29 +412,146 @@ ai_coaching_session = openai_client.chat(
 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, locals: {name: "John", app: "MyApp"})
+output = Promptly.render_template(template, locals: {name: "John", app: "MyApp"})
 
 # Render Liquid directly
 template = "Hello {{ name }}, welcome to {{ app }}!"
-output = Promptly.render(template, locals: {name: "John", app: "MyApp"}, engine: :liquid)
+output = Promptly.render_template(template, locals: {name: "John", app: "MyApp"}, engine: :liquid)
 ```
 
+## 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.
+
+## 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)
+
 ## API Reference
 
-### `Promptly.preview(identifier, locale: nil, locals: {})`
+### `Promptly.render(identifier, locale: nil, locals: {}, cache: true, ttl: nil)`
 
-Renders a template by identifier with locale fallback.
+Renders a template by identifier with locale fallback and optional caching.
 
 - **identifier**: Template path like `"user_onboarding/welcome"`
 - **locale**: Specific locale (defaults to `I18n.locale`)
 - **locals**: Hash of variables for template
+- **cache**: Enable/disable caching for this call (defaults to `true`)
+- **ttl**: Time-to-live in seconds for cache entry (overrides default TTL)
 
-### `Promptly.render(template, locals: {}, engine: :erb)`
+### `Promptly.render_template(template, locals: {}, engine: :erb)`
 
 Renders template string directly.
 

data/lib/generators/promptly/prompt_generator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Rails generator: promptly:prompt
+# Usage:
+#   rails g promptly:prompt user_onboarding/welcome_email --locales en es --engine erb
+# Creates prompt templates under app/prompts/ following conventions.
+
+require "fileutils"
+
+begin
+  require "rails/generators"
+  require "rails/generators/named_base"
+rescue LoadError
+  # Allow gem to load without Rails present
+end
+
+module Promptly
+  module Generators
+    class PromptGenerator < (defined?(Rails::Generators::NamedBase) ? Rails::Generators::NamedBase : Object)
+      if defined?(Rails::Generators::NamedBase)
+        argument :name, type: :string, required: true, desc: "Prompt identifier, e.g., user_onboarding/welcome_email"
+
+        class_option :engine, type: :string, default: "erb", desc: "Template engine: erb or liquid"
+        class_option :locales, type: :array, default: [], desc: "Locales to generate (e.g., en es fr)"
+        class_option :no_locale, type: :boolean, default: false, desc: "Generate only fallback (no locale suffix)"
+        class_option :force, type: :boolean, default: false, desc: "Overwrite existing files"
+
+        def create_prompt_files
+          id_path = name.to_s
+          base_dir = File.join("app", "prompts", File.dirname(id_path))
+          basename = File.basename(id_path)
+
+          FileUtils.mkdir_p(base_dir)
+
+          ext = engine_extension
+          resolve_targets(basename, ext).each do |rel|
+            path = File.join(base_dir, rel)
+            if File.exist?(path) && !options[:force]
+              say_status :skip, path
+              next
+            end
+            create_file(path, content_for_engine(ext), force: true)
+          end
+        end
+
+        private
+
+        def engine_extension
+          engine = options[:engine].to_s.downcase
+          case engine
+          when "erb" then "erb"
+          when "liquid" then "liquid"
+          else
+            say_status :error, "Unknown engine '#{engine}'. Use erb or liquid.", :red
+            exit(1)
+          end
+        end
+
+        def resolved_locales
+          return [] if options[:no_locale]
+
+          if options[:locales].any?
+            options[:locales].map(&:to_s)
+          elsif defined?(I18n) && I18n.respond_to?(:available_locales)
+            Array(I18n.available_locales).map(&:to_s)
+          else
+            ["en"]
+          end
+        end
+
+        def resolve_targets(basename, ext)
+          locs = resolved_locales
+          if options[:no_locale] || locs.empty?
+            ["#{basename}.#{ext}"]
+          else
+            locs.uniq.map { |loc| "#{basename}.#{loc}.#{ext}" }
+          end
+        end
+
+        def content_for_engine(ext)
+          case ext
+          when "erb"
+            <<~ERB
+              <!-- Prompt: generated by promptly:prompt -->
+              <!-- Identifier: #{name} -->
+
+              You are an AI assistant. Fill in content below using provided locals.
+
+              Context:
+              - Example local: <%= example || "value" %>
+
+              Task:
+              1. Explain the goal.
+              2. Provide actionable steps.
+              3. Keep it concise and clear.
+            ERB
+          when "liquid"
+            <<~LIQ
+              {# Prompt: generated by promptly:prompt #}
+              {# Identifier: #{name} #}
+
+              You are an AI assistant. Fill in content below using provided locals.
+
+              Context:
+              - Example local: {{ example | default: "value" }}
+
+              Task:
+              1. Explain the goal.
+              2. Provide actionable steps.
+              3. Keep it concise and clear.
+            LIQ
+          end
+        end
+      end
+    end
+  end
+end

data/lib/promptly/cache.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Promptly
+  class Cache
+    class << self
+      attr_accessor :store, :enabled, :ttl
+
+      def configure
+        yield self
+      end
+
+      def enabled?
+        @enabled != false && store
+      end
+
+      def fetch(key, ttl: nil, &block)
+        return yield unless enabled?
+
+        cache_key = generate_key(key)
+        cached_value = store.read(cache_key)
+
+        if cached_value
+          cached_value
+        else
+          value = yield
+          store.write(cache_key, value, expires_in: ttl || self.ttl)
+          value
+        end
+      end
+
+      def clear
+        return unless enabled? && store.respond_to?(:clear)
+
+        store.clear
+      end
+
+      def delete(key)
+        return unless enabled?
+
+        cache_key = generate_key(key)
+        store.delete(cache_key)
+      end
+
+      private
+
+      def generate_key(key_data)
+        case key_data
+        when String
+          "promptly:#{key_data}"
+        when Hash
+          content = key_data.sort.to_s
+          hash = Digest::SHA256.hexdigest(content)
+          "promptly:#{hash}"
+        else
+          "promptly:#{Digest::SHA256.hexdigest(key_data.to_s)}"
+        end
+      end
+    end
+
+    # Default configuration
+    self.enabled = true
+    self.ttl = 3600 # 1 hour default TTL
+    self.store = nil
+  end
+end

data/lib/promptly/helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Promptly
+  module Helper
+    # Render a prompt template by identifier.
+    #
+    # Example:
+    #   # app/prompts/welcome_email.erb
+    #   # Hello <%= @user.name %>, welcome!
+    #
+    #   # In a mailer, job, or service including this module:
+    #   # render_prompt("welcome_email", user: @user)
+    #
+    # Supports locale-aware lookup and caching.
+    def render_prompt(identifier, locale: nil, cache: true, ttl: nil, **locals)
+      Promptly.render(identifier, locale: locale, locals: locals, cache: cache, ttl: ttl)
+    end
+  end
+end

data/lib/promptly/railtie.rb

@@ -6,6 +6,26 @@ module Promptly
       # Intentionally minimal per DHH style; conventions over configuration
       # Hook points will be added as features land.
       Rails.logger.info("[promptly] loaded") if defined?(Rails.logger)
+
+      # Auto-configure Rails cache if available
+      if defined?(Rails.cache)
+        Promptly::Cache.store = Rails.cache
+      end
+
+      # Make render_prompt available in mailers, jobs, and controllers
+      if defined?(ActiveSupport)
+        ActiveSupport.on_load(:action_mailer) do
+          include Promptly::Helper
+        end
+
+        ActiveSupport.on_load(:active_job) do
+          include Promptly::Helper
+        end
+
+        ActiveSupport.on_load(:action_controller) do
+          include Promptly::Helper
+        end
+      end
     end
 
     rake_tasks do

data/lib/promptly/renderer.rb

@@ -26,6 +26,12 @@ module Promptly
       lookup = ActionView::LookupContext.new(ActionView::PathSet.new([]))
       av = view_class.new(lookup, {}, nil)
 
+      # Make locals available both as locals and instance variables (e.g., @user)
+      (locals || {}).each do |k, v|
+        ivar = "@#{k}"
+        av.instance_variable_set(ivar, v)
+      end
+
       av.render(inline: template, type: :erb, locals: locals || {})
     end
 

data/lib/promptly/tasks/ai_prompts.rake

@@ -1,25 +1,143 @@
 # frozen_string_literal: true
 
 namespace :ai_prompts do
-  desc "Preview a prompt: rake ai_prompts:preview[identifier,locale]"
-  task :preview, [:identifier, :locale] => :environment do |_, args|
+  desc "Render a prompt: rake ai_prompts:render[identifier,locale]"
+  task :render, [:identifier, :locale] => :environment do |_, args|
     identifier = args[:identifier]
     locale = args[:locale]
     prompts_path = ENV["PROMPTS_PATH"]
 
     unless identifier
-      warn "Usage: rake ai_prompts:preview[identifier,locale]"
+      warn "Usage: rake ai_prompts:render[identifier,locale]"
       exit 1
     end
 
     begin
       Promptly.prompts_path = prompts_path if prompts_path
 
-      output = Promptly.preview(identifier, locale: locale)
+      output = Promptly.render(identifier, locale: locale)
       puts output
     rescue Promptly::Error => e
       warn "Error: #{e.class}: #{e.message}"
       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}#{identifier_filter ? " for '#{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
 end

data/lib/promptly/version.rb

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

data/lib/promptly.rb

@@ -3,11 +3,13 @@
 require_relative "promptly/version"
 require_relative "promptly/renderer"
 require_relative "promptly/locator"
+require_relative "promptly/cache"
+require_relative "promptly/helper"
 
 module Promptly
   class Error < StandardError; end
 
-  def self.render(template, locals: {}, engine: :erb)
+  def self.render_template(template, locals: {}, engine: :erb)
     Renderer.render(template, locals: locals, engine: engine)
   end
 
@@ -20,10 +22,27 @@ module Promptly
     @prompts_path = path
   end
 
-  # Preview a template by identifier using locator rules
+  # Render a template by identifier using locator rules
   # identifier: "user_onboarding/welcome"
   # locale: defaults to I18n.locale when available
-  def self.preview(identifier, locale: nil, locals: {})
+  def self.render(identifier, locale: nil, locals: {}, cache: true, ttl: nil)
+    if cache && Cache.enabled?
+      cache_key = {
+        identifier: identifier,
+        locale: locale,
+        locals: locals,
+        prompts_path: prompts_path
+      }
+
+      Cache.fetch(cache_key, ttl: ttl) do
+        render_without_cache(identifier, locale: locale, locals: locals)
+      end
+    else
+      render_without_cache(identifier, locale: locale, locals: locals)
+    end
+  end
+
+  private_class_method def self.render_without_cache(identifier, locale: nil, locals: {})
     path = Locator.resolve(identifier, locale: locale)
     raise Error, "Template not found for '#{identifier}' (locale: #{locale.inspect}) under #{prompts_path}" unless path
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promptly
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.13
 platform: ruby
 authors:
 - Wilbur Suero
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-16 00:00:00.000000000 Z
+date: 2025-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.2'
 description: Build maintainable, localized, and testable AI prompts using ERB or Liquid
   templates with Rails conventions
 email:
@@ -75,17 +89,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".ruby-version"
 - ".standard.yml"
 - LICENSE
 - README.md
 - Rakefile
+- lib/generators/promptly/prompt_generator.rb
 - lib/promptly.rb
+- lib/promptly/cache.rb
+- lib/promptly/helper.rb
 - lib/promptly/locator.rb
 - lib/promptly/railtie.rb
 - lib/promptly/renderer.rb
 - lib/promptly/tasks/ai_prompts.rake
 - lib/promptly/version.rb
-- promptly.gemspec
 homepage: https://github.com/wilburhimself/promptly
 licenses:
 - MIT
@@ -103,7 +120,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/promptly.gemspec

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/promptly/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "promptly"
-  spec.version = Promptly::VERSION
-  spec.authors = ["Wilbur Suero"]
-  spec.email = ["wilbur@example.com"]
-
-  spec.summary = "Opinionated Rails integration for reusable AI prompt templates"
-  spec.description = "Build maintainable, localized, and testable AI prompts using ERB or Liquid templates with Rails conventions"
-  spec.homepage = "https://github.com/wilburhimself/promptly"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/wilburhimself/promptly"
-  spec.metadata["changelog_uri"] = "https://github.com/wilburhimself/promptly/blob/main/CHANGELOG.md"
-  spec.metadata["documentation_uri"] = "https://github.com/wilburhimself/promptly/blob/main/README.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  gemfiles = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.files = gemfiles
-
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Runtime dependencies
-  spec.add_dependency "actionview", "~> 7.0"
-
-  # Development dependencies
-  spec.add_development_dependency "rspec", "~> 3.12"
-  spec.add_development_dependency "standard", "~> 1.37"
-  spec.add_development_dependency "liquid", "~> 5.5"
-end