promptly 0.1.2 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23c7ae8e3735bb7596001fa52d79a218068be2f0c03ddbb1a5fb8aa263035489
-  data.tar.gz: a44b67aa11f2ca04c26c6b291369d4f6c7c9044c5bd61ed8cfc921b01afd9df5
+  metadata.gz: 55ee620ab3faf1e3c2d2ff44db3f28fe255a7379431c360f86b6f8dd87a8a752
+  data.tar.gz: ddf1db22fc260b4007e374944833b4ffe08fd5bcab020a033a28956612a26bbc
 SHA512:
-  metadata.gz: 382205e203447a670cb437b0a04a8ad42d137fe887d5690afe50bc3402f13be5b1ec0395e7d9450420aa60d7ae194283b3211dd1a417f620555733d2bb6d0859
-  data.tar.gz: 90b523fa6fa36447e72e4dfda79c500510448bd9f4ed1a9353b30bae7b024d8a13b4d753cdb522f56bdab59dcea40d0be532b7fd8afdc51c5caf6abe66cdba4a
+  metadata.gz: 0f343de865b5a2bef48f3a86cd131c40b8173be6183267fbd22242b228b668891ea191c7dba2597db373a7814bb30e05b8b8e4004cf345defef1d2e84c7b9b92
+  data.tar.gz: 3e872512ba87aa8f387d851d75d378e7b9cba91a20bbc0c316598af80166a71d691751e3a00a1aefda20a132f88e5a9bb58414ba312760dbc02dacec590bc11e

data/.ruby-version

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

data/README.md

@@ -1,3 +1,37 @@
+## 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.
+
+## API Reference
 # 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 +41,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 +117,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 +144,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 +160,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,14 +172,14 @@ 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]
 ```
 
 ## Rails App Integration
@@ -155,7 +190,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 +254,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 +337,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 +349,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 +391,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 +419,74 @@ 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)
 ```
 
 ## 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/railtie.rb

@@ -6,6 +6,11 @@ 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
     end
 
     rake_tasks do

data/lib/promptly/tasks/ai_prompts.rake

@@ -1,21 +1,21 @@
 # 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}"

data/lib/promptly/version.rb

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

data/lib/promptly.rb

@@ -3,11 +3,12 @@
 require_relative "promptly/version"
 require_relative "promptly/renderer"
 require_relative "promptly/locator"
+require_relative "promptly/cache"
 
 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 +21,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
 

data/promptly.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   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.required_ruby_version = ">= 3.3", "< 3.4"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -34,11 +34,13 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Runtime dependencies
-  spec.add_dependency "actionview", "~> 7.0"
+  # Runtime dependencies (single target: Rails 7.2.x)
+  spec.add_dependency "actionview", "~> 7.2"
 
   # Development dependencies
   spec.add_development_dependency "rspec", "~> 3.12"
   spec.add_development_dependency "standard", "~> 1.37"
   spec.add_development_dependency "liquid", "~> 5.5"
+  # Development dependencies
+  spec.add_development_dependency "railties", "~> 7.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: promptly
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.7
 platform: ruby
 authors:
 - Wilbur Suero
@@ -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,11 +89,14 @@ 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/locator.rb
 - lib/promptly/railtie.rb
 - lib/promptly/renderer.rb
@@ -103,7 +120,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="