rapidkit 0.37.0 → 0.38.0

package/docs/AI_FEATURES.md

@@ -0,0 +1,460 @@
+# 🤖 RapidKit AI Features
+
+AI-powered module recommendations using OpenAI embeddings to help you build faster.
+
+## 🚀 Quick Start
+
+### Option 1: Automatic Setup (Recommended)
+
+Just use AI recommendations - it will guide you through setup automatically!
+
+```bash
+# First time - AI will detect missing embeddings and offer to generate them
+npx rapidkit ai recommend "user authentication with social login"
+
+# Output:
+# ⚠️  Module embeddings not found
+# AI recommendations require embeddings to be generated.
+#
+# ? What would you like to do?
+#   🚀 Generate embeddings now (requires OpenAI API key)
+#   📝 Show me how to generate them manually
+#   ❌ Cancel
+
+# Choose option 1, provide API key, and embeddings will be generated automatically!
+```
+
+### Option 2: Manual Setup
+
+**Step 1:** Get OpenAI API key from [OpenAI Platform](https://platform.openai.com/api-keys)
+
+**Step 2:** Configure API key
+```bash
+npx rapidkit config set-api-key
+# Or (non-interactive environments):
+export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
+```
+
+**Step 3:** Generate embeddings (one-time, provider-cost dependent)
+```bash
+npx rapidkit ai generate-embeddings
+
+# Output:
+# 🤖 Generating AI embeddings for RapidKit modules...
+# 📡 Fetching modules from RapidKit...
+# ✓ Found <N> modules
+#
+# 💰 Estimated cost: shown by CLI at runtime
+#    (depends on provider pricing, model, and module count)
+#
+# ? Generate embeddings now? Yes
+# ✔ Generated embeddings for <N> modules
+# ✅ Embeddings generated successfully!
+```
+
+**Step 4:** Use AI recommendations
+```bash
+npx rapidkit ai recommend "user authentication"
+```
+
+### Option 3: Mock Mode (Testing Without API Key)
+
+Test AI features without an OpenAI API key using deterministic embeddings:
+
+```bash
+# No API key? No problem! Mock mode activates automatically
+npx rapidkit ai recommend "authentication"
+
+# Output:
+# ⚠️  OpenAI API key not configured - using MOCK MODE for testing
+#
+# 📝 Note: Mock embeddings provide approximate results for testing.
+#    For production, configure your OpenAI API key:
+# ...
+```
+
+Mock mode provides realistic (but not perfect) results for development and testing.
+
+## 📦 Features
+
+### AI Module Recommender
+
+Get intelligent module suggestions based on natural language descriptions.
+
+**Example:**
+```bash
+$ npx rapidkit ai recommend "I need user authentication with email"
+
+📦 Recommended Modules:
+
+1. authentication-core ⭐
+   Complete authentication system with password hashing, JWT tokens, OAuth 2.0
+   Match: 98% - Matches: auth, login, password
+
+2. email ⭐
+   Email sending with templates, SMTP/SendGrid/AWS SES support
+   Match: 95% - Matches: email, notification
+
+3. users-core
+   User management system with profiles, roles, permissions
+   Match: 92% - Matches: user, profile
+
+💡 Quick install (top 3):
+   rapidkit add module authentication-core email users-core
+```
+
+## 💰 Pricing
+
+### One-Time Setup Cost (Estimates)
+| Item | Cost | Notes |
+|------|------|-------|
+| Generate embeddings | Varies | One-time only, depends on model and module count |
+| Update embeddings | Varies | Only when catalog changes |
+
+### Per-Query Cost (After Setup, Estimates)
+| Usage | Cost | Notes |
+|-------|------|-------|
+| Single query | Very low | Depends on provider/model |
+| 100 queries | Low | Depends on provider/model |
+| 1,000 queries | Moderate | Depends on provider/model |
+| 10,000 queries | Higher | Depends on provider/model |
+
+**Important:** Provider pricing and limits change over time. Always validate current pricing/limits in the provider dashboard before budgeting.
+
+💡 **Tip:** Embeddings are generated once and reused, so ongoing query cost is typically much lower than initial setup.
+
+## 🔧 Configuration
+
+### View Current Config
+```bash
+npx rapidkit config show
+```
+
+### Set API Key
+```bash
+npx rapidkit config set-api-key
+```
+
+### Remove API Key
+```bash
+npx rapidkit config remove-api-key
+```
+
+### Enable/Disable AI
+```bash
+npx rapidkit config ai enable
+npx rapidkit config ai disable
+```
+
+## 📊 How It Works
+
+### Architecture Overview
+
+```
+┌─────────────────┐
+│  User Query     │  "I need authentication"
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ OpenAI API      │  Convert text → embedding vector (1536 dims)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Module Catalog  │  27+ modules with pre-generated embeddings
+│ (Dynamic)       │  Fetched from RapidKit Python Core
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Cosine          │  Calculate similarity scores
+│ Similarity      │  Find closest matches
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Ranked Results  │  Top N modules with scores & reasons
+└─────────────────┘
+```
+
+### Technical Details
+
+1. **Module Catalog**: 
+   - 27+ production-ready modules (dynamic from Python Core)
+   - Fallback to 11 hardcoded modules if Python unavailable
+   - 5-minute cache for performance
+
+2. **Embeddings**: 
+   - AI converts module descriptions to 1536-dimensional vectors
+   - Generated once, reused for all queries
+   - Stored in `data/modules-embeddings.json` (508KB)
+
+3. **Semantic Search**: 
+   - User query → embedding vector
+   - Cosine similarity with all modules
+   - Results sorted by relevance score (0-100%)
+
+4. **Smart Features**:
+   - Dependency detection (shows required modules)
+   - Match explanation (shows why module matched)
+   - Category grouping (auth, database, payment, etc.)
+   - Installation order calculation
+
+**Technology Stack:**
+- Model: `text-embedding-3-small` (OpenAI)
+- Dimension: 1536 vectors
+- Accuracy: 92%+ match scores
+- Cost: provider-dependent (check current provider pricing)
+
+**Performance:**
+- First query: ~200ms (embedding generation)
+- Subsequent queries: ~50ms (cached embeddings)
+- Catalog refresh: Every 5 minutes
+
+## 🎯 Use Cases
+
+### E-commerce Platform
+```bash
+rapidkit ai recommend "e-commerce with payments and inventory"
+```
+
+### SaaS Application
+```bash
+rapidkit ai recommend "SaaS platform with subscriptions"
+```
+
+### Real-time Chat
+```bash
+rapidkit ai recommend "real-time chat application"
+```
+
+### API Gateway
+```bash
+rapidkit ai recommend "API gateway with rate limiting"
+```
+
+## 🔒 Security
+
+- API keys stored in `$HOME/.rapidkit/config.json`
+- File permissions: `600` (owner read/write only)
+- Never committed to git (`.rapidkit/` in `.gitignore`)
+- Environment variable supported (`OPENAI_API_KEY`)
+
+## 🐛 Troubleshooting
+
+### "Module embeddings not found"
+
+**Solution:** Embeddings generate automatically on first use! Just follow the prompts:
+
+```bash
+npx rapidkit ai recommend "auth"
+
+# You'll see:
+# ⚠️  Module embeddings not found
+# ? What would you like to do?
+#   🚀 Generate embeddings now (requires OpenAI API key)
+#   📝 Show me how to generate them manually
+#   ❌ Cancel
+```
+
+Or generate manually:
+```bash
+npx rapidkit ai generate-embeddings
+```
+
+### "OpenAI API key not configured"
+
+**Option 1:** Mock mode (no key needed, for testing)
+```bash
+# Just use it! Mock mode activates automatically
+npx rapidkit ai recommend "database"
+```
+
+**Option 2:** Get a real API key
+```bash
+# 1. Get key: https://platform.openai.com/api-keys
+# 2. Configure it:
+npx rapidkit config set-api-key
+
+# Or set environment variable:
+export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
+```
+
+### "Invalid API key" or "401 Error"
+
+**Cause:** API key is incorrect or expired
+
+**Solution:**
+```bash
+# Update your API key
+npx rapidkit config set-api-key
+
+# Verify it's set correctly
+npx rapidkit config show
+```
+
+### "429 Rate Limited" or "Quota Exceeded"
+
+**Cause:** OpenAI API quota or rate limit reached
+
+**Solutions:**
+1. **Check billing:** https://platform.openai.com/account/billing
+2. **Check limits:** https://platform.openai.com/account/limits
+3. **Upgrade tier:** Free tier has lower limits
+4. **Wait:** Rate limits reset automatically
+
+**Rate Limits:**
+- Limits vary by provider account tier and can change over time
+- Check your provider dashboard for current request/token limits
+
+### "Failed to fetch modules from Python Core"
+
+**Cause:** RapidKit Python not installed or not in PATH
+
+**Impact:** Uses fallback catalog instead of the full runtime catalog
+
+**Solution (optional):**
+```bash
+# Install RapidKit Python Core
+pip install -e /path/to/rapidkit-core
+
+# Verify installation
+rapidkit modules list --json
+```
+
+**Note:** Fallback still provides good results with core modules!
+
+### Embeddings Out of Date
+
+**Symptom:** New modules not appearing in recommendations
+
+**Solution:** Update embeddings with latest modules
+```bash
+npx rapidkit ai update-embeddings
+
+# This will:
+# 1. Fetch latest modules from Python Core
+# 2. Generate embeddings for new modules
+# 3. Update data/modules-embeddings.json
+```
+
+### Low Match Scores
+
+**Symptom:** All results show <70% match
+
+**Possible Causes:**
+1. Query too vague: "build something"
+2. Query too specific: "blockchain NFT marketplace with AI"
+3. No matching modules exist
+
+**Solutions:**
+- Make query more specific: "authentication" → "user authentication with JWT"
+- Try different keywords: "storage" instead of "blockchain"
+- Check available modules: `npx rapidkit ai info`
+
+### Mock Mode Results Not Accurate
+
+**Cause:** Mock embeddings are deterministic but not trained
+
+**Solution:** Use real OpenAI API for production
+```bash
+# Get API key and generate real embeddings
+npx rapidkit config set-api-key
+npx rapidkit ai generate-embeddings
+```
+
+### Check Current Configuration
+
+```bash
+# View all settings
+npx rapidkit config show
+
+# Output shows:
+# - AI enabled: true/false
+# - API key: <masked>
+# - Embeddings status: exists/not found
+# - Module count: <N> modules
+```
+
+### Still Having Issues?
+
+1. **Enable debug logging:**
+   ```bash
+   DEBUG=rapidkit:* npx rapidkit ai recommend "auth"
+   ```
+
+2. **Check for updates:**
+   ```bash
+   npm outdated rapidkit
+   npm update rapidkit
+   ```
+
+3. **Report issue:**
+   - GitHub: https://github.com/rapidkitlabs/rapidkit-npm/issues
+   - Include: error message, OS, Node version, command used
+
+## 📚 Commands Reference
+
+### AI Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `rapidkit ai recommend [query]` | Get module recommendations | `rapidkit ai recommend "auth"` |
+| `rapidkit ai recommend [query] -n <N>` | Get top N recommendations | `rapidkit ai recommend "database" -n 3` |
+| `rapidkit ai recommend [query] --json` | Get JSON output | `rapidkit ai recommend "auth" --json` |
+| `rapidkit ai generate-embeddings` | Generate embeddings (one-time) | `rapidkit ai generate-embeddings` |
+| `rapidkit ai generate-embeddings --force` | Force regenerate embeddings | `rapidkit ai generate-embeddings --force` |
+| `rapidkit ai update-embeddings` | Update with latest modules | `rapidkit ai update-embeddings` |
+| `rapidkit ai info` | Show AI features info | `rapidkit ai info` |
+
+### Configuration Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `rapidkit config set-api-key` | Set OpenAI API key (interactive) | `rapidkit config set-api-key` |
+| `rapidkit config show` | Show current config | `rapidkit config show` |
+| `rapidkit config remove-api-key` | Remove API key | `rapidkit config remove-api-key` |
+| `rapidkit config ai enable` | Enable AI features | `rapidkit config ai enable` |
+| `rapidkit config ai disable` | Disable AI features | `rapidkit config ai disable` |
+
+### Recommend Command Options
+
+```bash
+rapidkit ai recommend [query] [options]
+
+Options:
+  -n, --number <count>  Number of recommendations (default: 5)
+  --json               Output as JSON
+  -h, --help           Display help
+```
+
+### Generate-Embeddings Command Options
+
+```bash
+rapidkit ai generate-embeddings [options]
+
+Options:
+  --force    Force regeneration even if embeddings exist
+  -h, --help Display help
+```
+
+## 🚀 Coming Soon
+
+- [ ] Code completion (GPT-4)
+- [ ] Codebase chat
+- [ ] Bug detection
+- [ ] Test generation
+- [ ] Architecture suggestions
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## 📄 License
+
+MIT - See [LICENSE](../LICENSE)
+
+---
+
+**Questions?** Open an issue on [GitHub](https://github.com/rapidkitlabs/rapidkit-npm/issues)

package/docs/AI_QUICKSTART.md

@@ -0,0 +1,245 @@
+# 🚀 AI Features - Quick Start Guide
+
+Get started with RapidKit AI recommendations in 60 seconds!
+
+## Option 1: Zero-Config Start (Recommended) ⚡
+
+Just run it - AI will guide you through everything:
+
+```bash
+npx rapidkit ai recommend "user authentication"
+```
+
+**First time?** You'll see this:
+
+```
+⚠️  Module embeddings not found
+AI recommendations require embeddings to be generated.
+
+? What would you like to do?
+  🚀 Generate embeddings now (requires OpenAI API key)
+  📝 Show me how to generate them manually
+  ❌ Cancel
+```
+
+Select option 1, provide your OpenAI API key, and you're done! 🎉
+
+## Option 2: Manual Setup (For Advanced Users)
+
+### Step 1: Get API Key (2 minutes)
+
+1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
+2. Click "Create new secret key"
+3. Copy your key
+
+### Step 2: Configure Key (30 seconds)
+
+```bash
+npx rapidkit config set-api-key
+# Paste your API key when prompted
+```
+
+Or set as environment variable:
+```bash
+export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
+```
+
+### Step 3: Generate Embeddings (typically about a minute, provider-cost dependent)
+
+```bash
+npx rapidkit ai generate-embeddings
+```
+
+You'll see:
+```
+🤖 Generating AI embeddings for RapidKit modules...
+📡 Fetching modules from RapidKit...
+✓ Found <N> modules
+
+💰 Estimated cost: shown by CLI at runtime
+   (depends on current provider pricing and module count)
+
+? Generate embeddings now? Yes
+```
+
+**This is a ONE-TIME cost!** Embeddings last forever.
+
+### Step 4: Use It! (Instant)
+
+```bash
+npx rapidkit ai recommend "authentication with social login"
+```
+
+Output:
+```
+📦 Recommended Modules:
+
+1. Authentication Core
+   Complete authentication with JWT, OAuth 2.0, secure sessions
+   Match: 95.2% - Matches: auth, login, oauth
+   Category: auth
+
+2. Users Core
+   User management with profiles, roles, permissions
+   Match: 88.7% - Matches: user, social
+   Category: auth
+   Requires: authentication-core
+
+💡 Quick install (top 3):
+   rapidkit add module authentication-core users-core
+
+? Would you like to install these modules now? Yes
+✅ Selected modules installed successfully
+```
+
+## Option 3: Test Without API Key (Mock Mode)
+
+No API key? No problem! Try it in mock mode:
+
+```bash
+npx rapidkit ai recommend "database with caching"
+```
+
+You'll see:
+```
+⚠️  OpenAI API key not configured - using MOCK MODE for testing
+
+📝 Note: Mock embeddings provide approximate results for testing.
+   For production, configure your OpenAI API key:
+   ...
+```
+
+Mock mode gives realistic (but not perfect) results for free!
+
+## 🎯 Common Use Cases
+
+### Find Authentication Modules
+```bash
+npx rapidkit ai recommend "user authentication with email and password"
+npx rapidkit ai recommend "social login with Google and Facebook"
+npx rapidkit ai recommend "two-factor authentication"
+```
+
+### Find Database Modules
+```bash
+npx rapidkit ai recommend "PostgreSQL database with migrations"
+npx rapidkit ai recommend "MongoDB with async operations"
+npx rapidkit ai recommend "database caching with Redis"
+```
+
+### Find Payment Modules
+```bash
+npx rapidkit ai recommend "payment processing with Stripe"
+npx rapidkit ai recommend "subscription billing"
+npx rapidkit ai recommend "invoice generation"
+```
+
+### Find Communication Modules
+```bash
+npx rapidkit ai recommend "email notifications with templates"
+npx rapidkit ai recommend "SMS verification codes"
+npx rapidkit ai recommend "real-time notifications"
+```
+
+### Find Infrastructure Modules
+```bash
+npx rapidkit ai recommend "background job processing"
+npx rapidkit ai recommend "file storage with S3"
+npx rapidkit ai recommend "rate limiting for APIs"
+```
+
+## 💡 Pro Tips
+
+### 1. Be Specific
+❌ Bad: "authentication"  
+✅ Good: "user authentication with JWT and OAuth 2.0"
+
+### 2. Mention Technologies
+❌ Bad: "database"  
+✅ Good: "PostgreSQL database with async support"
+
+### 3. Describe Your Use Case
+❌ Bad: "payments"  
+✅ Good: "subscription payments with recurring billing"
+
+### 4. Use Natural Language
+❌ Don't: "auth jwt oauth session redis"  
+✅ Do: "I need authentication with JWT tokens and Redis sessions"
+
+### 5. Get More/Less Results
+```bash
+# Get top 3 only
+npx rapidkit ai recommend "auth" --number 3
+
+# Get top 10
+npx rapidkit ai recommend "auth" --number 10
+```
+
+### 6. JSON Output for Scripts
+```bash
+npx rapidkit ai recommend "database" --json | jq '.recommendations[0].module.id'
+```
+
+## 🔧 Quick Commands
+
+```bash
+# Get recommendations
+npx rapidkit ai recommend "query here"
+
+# Generate embeddings (one-time)
+npx rapidkit ai generate-embeddings
+
+# Update embeddings (after RapidKit update)
+npx rapidkit ai update-embeddings
+
+# View info and pricing
+npx rapidkit ai info
+
+# Configure API key
+npx rapidkit config set-api-key
+
+# Check current config
+npx rapidkit config show
+```
+
+## 💰 Pricing Summary
+
+| Item | Cost | When |
+|------|------|------|
+| Setup (embeddings) | Varies | One-time only |
+| Per query | Varies | Every query |
+| Ongoing usage | Varies | After setup |
+
+**Note:** pricing changes over time. Check your provider dashboard for current rates.
+
+## ❓ Troubleshooting
+
+### "Module embeddings not found"
+👉 Just follow the interactive prompts - they'll guide you!
+
+### "Invalid API key"
+```bash
+npx rapidkit config set-api-key
+# Enter your correct API key
+```
+
+### "Quota exceeded"
+👉 Check your billing: https://platform.openai.com/account/billing
+
+### Want to test without spending money?
+👉 Use mock mode - it works without an API key!
+
+## 🎓 Learn More
+
+- **Full Guide:** [AI_FEATURES.md](AI_FEATURES.md)
+- **Technical Details:** [AI_DYNAMIC_INTEGRATION.md](AI_DYNAMIC_INTEGRATION.md)
+- **Main README:** [../README.md](../README.md)
+
+## 🚀 Ready to Build?
+
+Start exploring modules with AI:
+```bash
+npx rapidkit ai recommend "what I want to build"
+```
+
+That's it! Happy building! 🎉