promptly 0.1.7 → 0.1.17

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]
+```

data/wiki/Rails-App-Integration.md

@@ -0,0 +1,116 @@
+## 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"]
+  }
+)
+```

data/wiki/Schema-Validation.md

@@ -0,0 +1,27 @@
+## Schema Validation
+
+Ensure all locals passed to templates match a defined schema, so missing or mistyped variables fail fast before sending to AI.
+
+### Schema File Next to Prompt
+
+For each prompt, create a `schema.yml` (or `.json`) file alongside the template.
+
+**Example:**
+
+`app/prompts/user_onboarding/welcome_email.schema.yml`
+
+```yml
+name: string
+app_name: string
+user_role: string
+features: array
+days_since_signup: integer
+```
+
+### Validation Layer in Promptly
+
+The validation is automatically triggered when you call `Promptly.render`. It will check for missing keys and (optionally) value types.
+
+Supported types: `string`, `integer`, `array`.
+
+If the validation fails, it will raise an `ArgumentError` for missing keys or a `TypeError` for mismatched types.

data/wiki/_Sidebar.md

@@ -0,0 +1,11 @@
+- [Home](https://github.com/wilburhimself/promptly/wiki)
+- [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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promptly
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.17
 platform: ruby
 authors:
 - Wilbur Suero
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-16 00:00:00.000000000 Z
+date: 2026-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -83,7 +97,7 @@ dependencies:
 description: Build maintainable, localized, and testable AI prompts using ERB or Liquid
   templates with Rails conventions
 email:
-- wilbur@example.com
+- suerowilbur@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -94,15 +108,31 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/prompts/test/prompt.en.erb
+- app/prompts/test/prompt_with_metadata.en.erb
 - 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/validator.rb
 - lib/promptly/version.rb
-- promptly.gemspec
+- wiki/Configuration.md
+- wiki/Functional-Prompt-Tests.md
+- wiki/Generators.md
+- wiki/Helper-render_prompt.md
+- wiki/Home.md
+- wiki/I18n-Prompts-Usage.md
+- wiki/Linting-Templates.md
+- wiki/Liquid-Templates.md
+- wiki/Prompt-Version-Metadata.md
+- wiki/Quick-Start.md
+- wiki/Rails-App-Integration.md
+- wiki/Schema-Validation.md
+- wiki/_Sidebar.md
 homepage: https://github.com/wilburhimself/promptly
 licenses:
 - MIT
@@ -120,7 +150,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.3'
+      version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.4'

data/promptly.gemspec

@@ -1,46 +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.3", "< 3.4"
-
-  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 (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