aethex-studio/CLAUDE_API_SETUP.md

# 🤖 Claude API Setup Guide

This guide will help you set up the Claude API for AeThex Studio's **cross-platform code translation** feature - the core competitive differentiator that enables translating code between Roblox, UEFN, Spatial, and Core.

---

## 🎯 Why You Need This

Without a Claude API key:
- ✅ All features work (platform switching, templates, editor)
- ❌ Translation shows **mock responses** (not real AI translation)

With a Claude API key:
- ✅ **Real AI-powered translation** Roblox ↔ UEFN ↔ Spatial ↔ Core
- ✅ Intelligent code conversion with explanations
- ✅ Platform-specific best practices applied
- ✅ Your #1 competitive advantage unlocked 🔥

---

## 📋 Prerequisites

- An Anthropic account
- Credit card for API billing (Claude API is pay-as-you-go)
- Estimated cost: **$0.001 - $0.01 per translation** (very affordable)

---

## 🔧 Step-by-Step Setup

### Step 1: Get Your Claude API Key

1. **Visit Anthropic Console**: https://console.anthropic.com/
2. **Create Account** (if you don't have one)
3. **Navigate to API Keys**: https://console.anthropic.com/settings/keys
4. **Click "Create Key"**
5. **Copy your API key** (starts with `sk-ant-api03-...`)

⚠️ **Important**: Save this key securely! You won't be able to see it again.

### Step 2: Configure Environment Variables

#### Option A: Local Development (.env.local)

1. Create a file named `.env.local` in the project root:

```bash
# From project root
touch .env.local
```

2. Add your API key:

```bash
# .env.local
VITE_CLAUDE_API_KEY=sk-ant-api03-your-actual-key-here
```

3. Restart your dev server:

```bash
npm run dev
```

#### Option B: Production Deployment (Vercel/Netlify)

**For Vercel:**
1. Go to your project settings
2. Navigate to "Environment Variables"
3. Add:
   - Key: `VITE_CLAUDE_API_KEY`
   - Value: `sk-ant-api03-your-actual-key-here`
4. Redeploy your app

**For Netlify:**
1. Site Settings → Environment Variables
2. Add:
   - Key: `VITE_CLAUDE_API_KEY`
   - Value: `sk-ant-api03-your-actual-key-here`
3. Trigger new deploy

---

## ✅ Verify Setup

### Test the Translation Feature

1. **Open AeThex Studio** in your browser
2. **Switch Platform** to Roblox (if not already)
3. **Select a Template** (e.g., "Hello World")
4. **Click "Translate" button** in toolbar
5. **Choose Target Platform** (e.g., UEFN)
6. **Click "Translate"**

**If configured correctly:**
- Loading spinner shows
- Real Verse code appears on the right side
- Explanation section shows key differences
- Warnings section (if applicable)

**If NOT configured:**
- Mock translation appears with comment: `-- TODO: Replace with actual uefn implementation`
- Warning: "Mock translation active - integrate Claude API for production"

---

## 💰 Cost Estimation

**Claude 3.5 Sonnet Pricing** (as of Jan 2025):
- **Input**: $3 per million tokens
- **Output**: $15 per million tokens

**Typical Translation Costs:**
- Small script (50 lines): ~$0.001
- Medium script (200 lines): ~$0.005
- Large script (500 lines): ~$0.015

**Example monthly usage:**
- 100 translations/day = ~$0.50/day = **~$15/month**
- 500 translations/day = ~$2.50/day = **~$75/month**

💡 **Tip**: Start with a $10 credit to test. Monitor usage in Anthropic Console.

---

## 🔒 Security Best Practices

### ✅ DO:
- ✅ Store API keys in `.env.local` (never in code)
- ✅ Add `.env.local` to `.gitignore`
- ✅ Use environment variables in production
- ✅ Rotate keys periodically
- ✅ Set spending limits in Anthropic Console

### ❌ DON'T:
- ❌ Commit API keys to Git
- ❌ Share keys publicly
- ❌ Hardcode keys in source code
- ❌ Use same key for dev and prod

---

## 🐛 Troubleshooting

### Issue: "API key not configured" warning

**Solution**:
- Verify `.env.local` exists and has correct key
- Restart dev server (`npm run dev`)
- Check console for errors

### Issue: "API request failed: 401"

**Solution**:
- Your API key is invalid or expired
- Generate new key in Anthropic Console
- Update `.env.local`

### Issue: "API request failed: 429"

**Solution**:
- Rate limit exceeded
- Check usage in Anthropic Console
- Add billing method if needed
- Implement client-side rate limiting (future enhancement)

### Issue: "API request failed: 400"

**Solution**:
- Invalid request format (shouldn't happen)
- Check browser console for details
- Report bug on GitHub

### Issue: Translation returns mock data despite having API key

**Solution**:
1. Open browser console (F12)
2. Look for: "Claude API key not configured, using mock translation"
3. Check environment variable name: Must be `VITE_CLAUDE_API_KEY`
4. Restart dev server after adding key

---

## 🧪 Advanced Configuration

### Custom Model Selection

Use a different Claude model (optional):

```bash
# .env.local
VITE_CLAUDE_API_KEY=sk-ant-api03-...
VITE_CLAUDE_MODEL=claude-3-opus-20240229
```

Available models:
- `claude-3-5-sonnet-20241022` (default, recommended)
- `claude-3-opus-20240229` (most capable, slower, expensive)
- `claude-3-haiku-20240307` (fastest, cheaper, less accurate)

### Rate Limiting (Future)

To implement client-side rate limiting:

```typescript
// src/lib/translation-engine.ts
const MAX_TRANSLATIONS_PER_MINUTE = 10;
```

---

## 📊 Monitoring Usage

### Anthropic Console

1. Visit: https://console.anthropic.com/settings/usage
2. View:
   - Total requests
   - Tokens consumed
   - Cost breakdown
   - Daily/monthly trends

### Set Spending Limits

1. Console → Settings → Billing
2. Set monthly limit (e.g., $50)
3. Get email alerts at 50%, 75%, 90%

---

## 🚀 Next Steps

Once you have the API key configured:

1. **Test All Translation Pairs**:
   - Roblox → UEFN
   - UEFN → Roblox
   - Roblox → Spatial (when templates added)

2. **Share with Team**:
   - Each developer needs their own API key
   - Or use shared key in production only

3. **Monitor Quality**:
   - Review translations for accuracy
   - Report issues on GitHub
   - Suggest prompt improvements

4. **Optimize Costs**:
   - Cache common translations (future)
   - Batch similar requests (future)
   - Use cheaper model for simple code (future)

---

## 💡 Tips for Best Results

### Writing Translatable Code

Claude works best with:
- ✅ Well-commented code
- ✅ Clear variable names
- ✅ Standard patterns (no weird hacks)
- ✅ Short to medium scripts (< 500 lines)

### Using the Context Field

When translating complex code, add context:

```
Context: "This is a player spawn system that needs to work with UEFN's agent system"
```

This helps Claude understand the purpose and translate more accurately.

---

## 🆘 Need Help?

- **Documentation Issues**: https://github.com/AeThex-LABS/aethex-studio/issues
- **Anthropic Support**: https://support.anthropic.com
- **API Status**: https://status.anthropic.com

---

## 📚 Additional Resources

- [Anthropic API Documentation](https://docs.anthropic.com/claude/reference/getting-started-with-the-api)
- [Claude Pricing](https://www.anthropic.com/pricing)
- [API Best Practices](https://docs.anthropic.com/claude/docs/api-best-practices)
- [Rate Limits](https://docs.anthropic.com/claude/reference/rate-limits)

---

**🎉 You're all set!** Your cross-platform translation engine is now powered by Claude AI. Start translating code between platforms and unlock your competitive advantage!