AI Suggestions

Feature: "Let AI Decide" button for map-plot generation Status: ✅ Implemented Date: 2026-02-03

Overview

This feature allows users to generate random, creative map descriptions using AI when creating map-plot content. Instead of having to write a description from scratch, users can click a button to get an AI-generated starting point that they can edit.

Implementation

API Endpoint

Route: POST /api/map-description/suggest

Features:

• Uses OpenAI GPT-4o (standard tier) for high-quality, creative descriptions
• Generates 100-250 character descriptions optimized for the 20-500 char requirement
• 12 different location templates for variety (ruins, fortresses, temples, dungeons, etc.)
• SRD 5.2 compliant (no trademarked WotC content)
• Logs to generation_logs table for analytics

Rate Limiting:

• 5 generations per hour per user (server-side, Redis)
• Returns rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• 429 status with helpful error message when limit exceeded
• Falls back to in-memory rate limiting in development

Response:

{
  "description": "A crumbling keep perched on...",
  "template": "a forgotten ruin",
  "model": "gpt-4o",
  "tokensUsed": 85,
  "remaining": 4
}

UI Component

Location: Map-Plot Generation page, Step 1 (Map Description)

Features:

• Sparkles icon (✨) button with "Let AI Decide" label
• 3-second cooldown between clicks (client-side)
• Shows countdown timer during cooldown ("Wait 3s", "Wait 2s", "Wait 1s")
• Displays remaining generations this hour: "(4/5 remaining this hour)"
• Loading state: "Generating..."
• Success toast: "Description generated! 4 remaining this hour."
• Error toast for rate limits: "Rate limit exceeded. Try again in X minutes."

Redis Rate Limiter

File: src/lib/redis/client.ts

Added:

• New mapDescriptionRateLimiter with 5 generations/hour sliding window
• New rate limit type: "map_description"
• Integrated with existing Upstash Redis infrastructure
• Falls back to in-memory for development

Cost Analysis

Per Generation:

• Model: GPT-4o (gpt-4o)
• Average tokens: ~150 total (100 input + 50 output)
• Cost: ~$0.003 per generation

Per User Per Hour:

• Max 5 generations
• Max cost: ~$0.015/hour per user

Monthly (heavy user):

• 5 gen/hour × 8 hours/day × 30 days = 1,200 generations
• Cost: ~$3.60/month per heavy user

User Flow

1. User navigates to /generate/map-plot
2. In Step 1, they see the "Let AI Decide" button above the description textarea
3. Click button → AI generates description in ~1-2 seconds
4. Description populates textarea
5. Counter shows remaining generations (e.g., "4/5 remaining this hour")
6. Button disabled for 3 seconds (cooldown)
7. User can edit the generated text before proceeding

Example Descriptions

Based on the 12 templates, here are example outputs:

• "A crumbling keep perched on a windswept cliff, its courtyard choked with thorny vines and the catacombs below echoing with strange whispers."
• "An ancient temple half-submerged in a misty swamp, stone pillars wrapped in glowing vines and the air thick with the hum of unseen magic."
• "A coastal settlement clinging to jagged rocks, its wooden docks battered by relentless waves while lanterns flicker in the fog."
• "A cursed battlefield where twisted weapons jut from scorched earth, and spectral figures drift through the permanent twilight."

Testing

Manual Testing

1. Start dev server: npm run dev
2. Navigate to: http://localhost:3000/generate/map-plot
3. Log in with valid credentials
4. Click "Let AI Decide" button
5. Verify:
   • Description appears in textarea
   • Counter decrements (5/5 → 4/5 → etc.)
   • 3-second cooldown enforces waiting
   • After 5 clicks, rate limit error appears

Rate Limit Testing

# Test rate limiting (requires authentication)
for i in {1..6}; do
  curl -X POST http://localhost:3000/api/map-description/suggest \
    -H "Cookie: sb-access-token=YOUR_TOKEN" \
    -H "Content-Type: application/json"
  echo ""
  sleep 1
done
# Expected: 5 successes, 1 failure with 429 status

Files Modified

Created

• src/app/api/map-description/suggest/route.ts - API endpoint

Modified

• src/app/[locale]/generate/map-plot/page.tsx - UI button and logic
• src/lib/redis/client.ts - Added mapDescriptionRateLimiter

Future Enhancements

• Add tone/style preferences (e.g., "gothic", "whimsical", "gritty")
• Allow users to request specific types of locations
• Show history of generated descriptions for inspiration
• Add "Regenerate" button to try again without editing
• Premium users get higher rate limits (10/hour)

Rollout Notes

• Feature is safe to deploy immediately
• Rate limiting prevents abuse
• Falls back gracefully if Redis unavailable
• No database migrations required
• Logs to existing generation_logs table