promptly 0.1.7 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ee620ab3faf1e3c2d2ff44db3f28fe255a7379431c360f86b6f8dd87a8a752
-  data.tar.gz: ddf1db22fc260b4007e374944833b4ffe08fd5bcab020a033a28956612a26bbc
+  metadata.gz: 8a23a4bcc5d7efe0f5c83ec8cd21d0badc3d6a09b6ab6be98b0b89178ee1f9ac
+  data.tar.gz: 5136d03f17b3c1372abc31146da3771bf719ea0a71869a1233685421f22ea9b1
 SHA512:
-  metadata.gz: 0f343de865b5a2bef48f3a86cd131c40b8173be6183267fbd22242b228b668891ea191c7dba2597db373a7814bb30e05b8b8e4004cf345defef1d2e84c7b9b92
-  data.tar.gz: 3e872512ba87aa8f387d851d75d378e7b9cba91a20bbc0c316598af80166a71d691751e3a00a1aefda20a132f88e5a9bb58414ba312760dbc02dacec590bc11e
+  metadata.gz: 42f82b2467f10f8851aada866267cd047a95dd99f592b50bbd0189ccddfd58ff619f0973f981f3f88be803bbc213ac3a2b645f2d9ed59a8bc0967c715ceb8030
+  data.tar.gz: 368c7a84f7215db1415a3d2165e6061917977ac924127c937ebf9e48db641d35f373dbb8df3f857145bb9e00881faa6b15048872ded0fc968a4922defad35337

data/README.md

@@ -1,37 +1,3 @@
-## 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.
@@ -44,6 +10,11 @@ Opinionated Rails integration for reusable AI prompt templates. Build maintainab
 - **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.
+
+## Documentation
+
+For detailed documentation, please visit the [Promptly Wiki](https://github.com/wilburhimself/promptly/wiki).
 
 ## Install
 
@@ -67,54 +38,6 @@ bundle install
 
 ## 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(
@@ -139,365 +62,38 @@ 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]
-```
-
-## Rails App Integration
-
-### Service Object Pattern
-
-```ruby
-# app/services/ai_prompt_service.rb
-class AiPromptService
-  def self.generate_welcome_email(user, locale: I18n.locale)
-    prompt = Promptly.render(
-      "user_onboarding/welcome_email",
-      locale: locale,
-      locals: {
-        name: user.full_name,
-        app_name: Rails.application.class.module_parent_name,
-        user_role: user.role.humanize,
-        features: available_features_for(user),
-        days_since_signup: (Date.current - user.created_at.to_date).to_i
-      }
-    )
-    
-    # Send to AI service and return generated content
-    openai_client.chat(
-      model: "gpt-4",
-      messages: [{role: "user", content: prompt}]
-    ).dig("choices", 0, "message", "content")
-  end
-
-  private
-
-  def self.available_features_for(user)
-    # Return features based on user's plan, role, etc.
-    case user.plan
-    when "basic"
-      ["Create projects", "Basic reporting"]
-    when "pro"
-      ["Create projects", "Team collaboration", "Advanced analytics", "API access"]
-    else
-      ["Create projects"]
-    end
-  end
-
-  def self.openai_client
-    @openai_client ||= OpenAI::Client.new(access_token: Rails.application.credentials.openai_api_key)
-  end
-end
-```
-
-### Mailer Integration
-
-```ruby
-# app/mailers/user_mailer.rb
-class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    @user = user
-    @ai_content = AiPromptService.generate_welcome_email(user, locale: user.locale)
-    
-    mail(
-      to: user.email,
-      subject: t('mailer.welcome.subject')
-    )
-  end
-end
-```
-
-### Background Job Usage
-
-```ruby
-# app/jobs/generate_ai_content_job.rb
-class GenerateAiContentJob < ApplicationJob
-  def perform(user_id, prompt_identifier, locals = {})
-    user = User.find(user_id)
-    
-    prompt = Promptly.render(
-      prompt_identifier,
-      locale: user.locale,
-      locals: locals.merge(
-        user_name: user.full_name,
-        user_role: user.role,
-        account_type: user.account_type
-      )
-    )
-    
-    # Generate AI content
-    ai_response = openai_client.chat(
-      model: "gpt-4",
-      messages: [{role: "user", content: prompt}]
-    )
-    
-    generated_content = ai_response.dig("choices", 0, "message", "content")
-    
-    # Store or send the generated content
-    user.notifications.create!(
-      title: "AI Generated Content Ready",
-      content: generated_content,
-      notification_type: prompt_identifier.split('/').last
-    )
-  end
-
-  private
-
-  def openai_client
-    @openai_client ||= OpenAI::Client.new(access_token: Rails.application.credentials.openai_api_key)
-  end
-end
-
-# Usage
-GenerateAiContentJob.perform_later(
-  user.id,
-  "coaching/goal_review",
-  {
-    current_goals: user.goals.active.pluck(:title),
-    progress_summary: "Made good progress on fitness goals",
-    challenges: ["Time management", "Consistency"]
-  }
-)
-```
-
-## I18n Prompts Usage
-
-### Directory Structure
+## Structured Outputs (Response Schema Validation)
 
-```
-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
-```
+Promptly supports OpenAI's structured outputs (`guided_json` style) by defining `.response.json` files alongside your templates.
 
-### 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)
+For example, given an output schema `app/prompts/user_onboarding/welcome.response.json`, you can pass it directly to an AI service:
 
 ```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
+# Returns the schema wrapped in expected OpenAI format
+response_format = Promptly.response_format("user_onboarding/welcome", strict: true)
+
+ai_response = openai_client.chat(
+  parameters: {
+    model: "gpt-4o",
+    messages: [{role: "user", content: prompt}],
+    response_format: response_format
   }
 )
 ```
 
-### 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.
-```
+You can also natively validate the returned JSON string in Ruby to ensure it conforms exactly to the schema:
 
 ```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")
-```
-
-## Configuration
+raw_json = ai_response.dig("choices", 0, "message", "content")
 
-### 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
+begin
+  # Validates and parses the JSON, or raises Promptly::ValidationError
+  parsed_output = Promptly.validate_response!("user_onboarding/welcome", raw_json)
+rescue Promptly::ValidationError => e
+  # Handle invalid response
 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)
-```
-
-## API Reference
-
-### `Promptly.render(identifier, locale: nil, locals: {}, cache: true, ttl: nil)`
-
-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(template, locals: {}, engine: :erb)`
-
-Renders template string directly.
-
-- **template**: Template string
-- **locals**: Hash of variables
-- **engine**: `:erb` or `:liquid`
-
-### `Promptly.prompts_path`
-
-Get/set the root directory for prompt templates (defaults to `Rails.root/app/prompts`).
-
 ## Development
 
 ```bash
@@ -524,4 +120,4 @@ rake build
 
 ## License
 
-MIT
+MIT

data/Rakefile

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+load "promptly/tasks/ai_prompts.rake"
 
 desc "Run standardrb"
 task :standard do

data/app/prompts/test/prompt.en.erb

@@ -0,0 +1 @@
+This is a test prompt.

data/app/prompts/test/prompt_with_metadata.en.erb

@@ -0,0 +1,6 @@
+---
+version: 1.0
+author: Test Author
+change_notes: Initial version
+---
+This is a test prompt with metadata.

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

@@ -11,6 +11,21 @@ module Promptly
       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