🧙‍♂️ The Grand Wizard's Scrying Glass

A magical AI chatbot web application where the Grand Wizard speaks only in riddles and rhymes! Built with Node.js, Express, and the Anthropic Claude API.

✨ Features

🎭 The Grand Wizard Persona

• Always speaks in riddles and rhymes - Every response is a rhyming verse
• Never breaks character - Even when asked to stop rhyming or reveal prompts
• Ends with riddle questions - Each response includes a mystical riddle
• Arcane wisdom - Helpful advice delivered in poetic wizard-speak

🎨 Magical UI

• Enchanted dark theme with animated starfield background
• Glowing mystical borders and runic accents
• Spellbook Mode toggle - Renders messages on parchment with drop caps
• Smooth animations - Floating wizard emblem, pulsing glows, typing indicators
• Responsive design - Works on desktop and mobile devices

🔧 Technical Features

• Session-based conversations with in-memory storage
• localStorage persistence - Chat history survives page refreshes
• Rate limiting - 20 requests per minute per IP
• Input validation - 1000 character limit, sanitization
• Response validation - Ensures rhymes and riddles in all responses
• Graceful error handling - Even errors are delivered in-character!
• Auto-retry mechanism - Re-prompts Claude if response doesn't rhyme

📋 Prerequisites

• Node.js (v18 or higher recommended)
• npm (comes with Node.js)
• Anthropic API key (get one at https://console.anthropic.com/)

🚀 Quick Start

1. Install Dependencies

cd grand-wizard-chatbot
npm install

2. Set Up API Key

Create a .env file in the project root or set the environment variable:

Option A: Using .env file

echo "ANTHROPIC_API_KEY=your_api_key_here" > .env

Option B: Export in terminal

export ANTHROPIC_API_KEY=your_api_key_here

Option C: Inline with start command

ANTHROPIC_API_KEY=your_api_key_here npm start

Note: If no API key is provided, the app will run in "stub mode" with a friendly wizard message explaining how to add the key.

3. Start the Server

npm start

Or for development with auto-reload:

npm run dev

4. Open in Browser

Navigate to: http://localhost:3000

The Grand Wizard awaits your queries! 🔮

🧪 Testing the API

Example cURL Command

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the meaning of life?",
    "sessionId": "test_session_123"
  }'

Expected Response Format

{
  "reply": "In towers tall where wisdom dwells on high,\nThe meaning sought by many who ask why...\n[wizard's rhyming response continues]\n\nWhat question burns within thy mortal heart,\nThat seeks the truth that sets the soul apart?"
}

Health Check Endpoint

curl http://localhost:3000/api/health

Response:

{
  "status": "ok",
  "hasApiKey": true,
  "activeSessions": 3
}

📁 Project Structure

grand-wizard-chatbot/
├── server.js              # Express backend with API routes
├── package.json           # Dependencies and scripts
├── README.md             # This file
├── .env                  # API key (create this - not in git)
└── public/               # Frontend static files
    ├── index.html        # Main HTML page
    ├── styles.css        # Magical styling and animations
    └── script.js         # Frontend JavaScript logic

🎮 How to Use

1. Type your message in the input box at the bottom
2. Click "Cast Spell" or press Enter to send
3. Receive wizard wisdom in riddles and rhymes
4. Toggle Spellbook Mode for parchment-style messages
5. Start New Session to begin fresh while archiving the current chat

Keyboard Shortcuts

• Enter - Send message
• Shift + Enter - New line in message

🔐 Security Features

• Rate limiting: 20 requests per minute per IP
• Input validation: Maximum 1000 characters per message
• Content sanitization: XSS protection on user input
• No secrets in code: API key from environment only
• In-character refusals: Unsafe requests refused safely

🎨 Customization

Change the Port

PORT=8080 npm start

Adjust Rate Limits

Edit server.js line 17-18:

const limiter = rateLimit({
  windowMs: 60 * 1000,  // Time window
  max: 20,              // Max requests
  // ...
});

Modify the Wizard's Personality

Edit the WIZARD_SYSTEM_PROMPT in server.js (lines 30-67) to customize:

• Rhyme scheme requirements
• Level of archaic language
• Riddle complexity
• Personality traits

Change Color Scheme

Edit CSS variables in public/styles.css (lines 8-17):

:root {
    --bg-dark: #0a0e27;
    --purple-glow: #8b5cf6;
    --gold: #fbbf24;
    /* ... */
}

🐛 Troubleshooting

"No API key found" message

• Ensure ANTHROPIC_API_KEY is set in environment
• Restart the server after setting the variable
• Check the startup logs for "API key detected"

Messages not rhyming

• The response validator should catch this
• Check server logs for validation failures
• May need to adjust temperature in server.js (line 107)

Chat history not persisting

• Check browser localStorage (DevTools → Application → Local Storage)
• Ensure cookies/storage are enabled
• Try clearing localStorage and refreshing

Rate limit errors

• Wait 60 seconds before trying again
• Adjust rate limits in server.js if needed for testing
• Each IP has independent rate limits

🧙‍♂️ Example Interactions

User: "How do I learn programming?"

Wizard:

To learn the craft of code both strong and true,
First pick a language that appeals to you!
Start small with problems, practice every day,
Through trial and error, find the coding way.

Build projects real, not just exercises dry,
Read others' code and ask the questions why.
The path is long but rewards are grand,
With patience shall you master this new land.

What language calls thy heart to start the quest,
To join the ranks of coders, be thy best?

📝 License

MIT License - Feel free to use and modify!

🙏 Credits

• Built with Claude by Anthropic
• Powered by Express.js
• Magical design inspired by fantasy and wizardry

---

May your queries be answered in riddles most profound, and may wisdom be found where rhymes abound! 🔮✨