AI Prompt Manager

Quick Start

Core Workflow

1. Create feature → Define what AI capability is needed
2. Create prompt template → Write system/user prompts with {{variables}}
3. Create prompt version → Implement the template (allows versioning)
4. Bind to environment → Connect prompt to dev/stage/prod
5. Configure provider → Choose vendor and model
6. Test via Admin panel → Validate response and cost

For SQL patterns, see sql-patterns.md.

Database Schema (Essentials)

| Table | Purpose | |-------|---------| | ai_features | Feature registry (key, description) | | ai_prompt_templates | Prompt structure (task, name) | | ai_prompt_versions | Prompt variants with {{variables}} | | ai_prompt_bindings | Link prompt version to environment | | ai_feature_bindings | Link feature to vendor/model/env | | ai_pricing | Cost per vendor/model | | ai_usage_logs | Track calls, tokens, cost per user |

Full schema: See Docs/context/db-schema-short.md.

Prompt Design

Variable Substitution

Use {{variable}} syntax for dynamic content:

system_prompt: "You are a {{role}} assistant for Bible study."
user_prompt_template: "Analyze: {{verse_reference}}"

// At call time
await getPrompt('my_feature', {
  role: 'theological scholar',
  verse_reference: 'John 3:16'
}, 'prod');

Output Schema

Define expected output structure to validate responses:

{
  "type": "object",
  "properties": {
    "summary": {"type": "string"},
    "insights": {
      "type": "array",
      "items": {"type": "string"}
    },
    "references": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Temperature & Tokens

• Temperature: 0.0–0.3 (factual), 0.4–0.7 (balanced), 0.8–1.0 (creative)
• max_tokens: Set based on expected output length
  • Verse lookup: ~50 tokens
  • Short analysis: ~200 tokens
  • Full commentary: ~1000+ tokens

See providers.md for full guidance.

Vendor & Model Configuration

Vendors: lovable, openai, anthropic, openrouter

Models are vendor-specific and change over time. Always:

1. Check current availability in the API docs
2. Test in dev environment first
3. Configure pricing in ai_pricing before promoting to prod

See providers.md for selection strategy.

Environment Strategy

1. dev – Test new prompts, experiment with vendors
2. stage – Validate cost estimates, pre-production testing
3. prod – Stable, cost-optimized features

Always follow: dev → stage → prod progression.

Testing AI Features

1. Go to Admin panel → AI section → Testaus tab
2. Select feature
3. Input test variables
4. Review response, tokens, cost estimate
5. Iterate on prompt if needed

Monorepo Integration

AI features work across workspace apps:

• raamattu-nyt (main Bible app) – Uses most AI features
• widgetizer (embed service) – Limited AI features
• Edge Functions – Orchestrate calls in ai-orchestrator/

All share same bible_schema database and configuration.

Skills Handoff

• Quota/plan limits → See subscription-system skill
• Cost optimization → See performance-auditor skill
• Edge Functions → See edge-function-generator skill

References

• sql-patterns.md – Common SQL workflows
• providers.md – Vendor/model selection and parameters
• Docs/06-AI-ARCHITECTURE.md – Full system design
• Docs/context/db-schema-short.md – Database schema details
• Docs/context/supabase-map.md – Edge Functions & access matrix