🍃 WispGPT Code Explainer

Transform any code into simple, greentext-style explanations using AI. Perfect for understanding complex codebases, reviewing changes, and making code accessible to everyone.

✨ Features

• 🔤 Greentext Recipes: Transform code into step-by-step > action format explanations
• 🌍 Multi-Language Support: JavaScript, Python, Java, C++, Go, Rust, and 15+ more languages
• 🤖 Multiple AI Providers: OpenAI, Anthropic (Claude), Google (Gemini), Cloudflare Workers AI
• 🔄 Diff Explanations: Understand what changed between code versions
• 💻 CLI Tool: Command-line interface for easy integration
• 🌐 Web Server: HTTP API and demo web interface
• 📦 Library: Use as a Node.js package in your projects
• ⚡ Fast: Optimized for quick explanations without overwhelming detail

🚀 Quick Start

Installation

# Install globally for CLI usage
npm install -g wispgpt-code-explainer

# Or install locally for library usage
npm install wispgpt-code-explainer

Setup

1. Get an API key from your preferred provider:

   • OpenAI (Recommended)
   • Anthropic
   • Google AI
   • Cloudflare Workers AI (Free tier available)

2. Configure your environment:

# Interactive setup
wispgpt setup

# Or manually create .env file
cp .env.example .env
# Edit .env with your API keys

CLI Usage

# Explain a code file
wispgpt explain --file src/app.js

# Explain code interactively (opens editor)
wispgpt explain

# Compare two versions
wispgpt diff --original old.js --modified new.js

# Use different AI provider
wispgpt explain --file script.py --provider anthropic

# Save output to file
wispgpt explain --file code.js --output recipe.txt

📖 Examples

Basic Code Explanation

Input:

function calculateTax(income, rate) {
  if (income <= 0) {
    throw new Error('Income must be positive');
  }
  
  const tax = income * (rate / 100);
  const afterTax = income - tax;
  
  return {
    original: income,
    tax: tax,
    afterTax: afterTax,
    rate: rate
  };
}

Output:

> analyze function parameters for income and rate
> validate income is positive number
> throw error if income is zero or negative
> calculate tax amount using percentage
> compute after-tax income
> return object with all calculated values
> recipe generation complete

Diff Explanation

When you modify code, WispGPT explains what changed:

> original validation logic
> **changed** simple email check **to** comprehensive regex validation
> **added** input type checking for string
> **added** email trimming before validation
> **changed** return boolean **to** throw descriptive errors
> improved error handling and validation accuracy

💻 Library Usage

import WispGPT from 'wispgpt-code-explainer';

// Initialize with your preferred provider
const wispgpt = new WispGPT({
  provider: 'openai',
  providerConfig: {
    apiKey: process.env.OPENAI_API_KEY
  }
});

// Explain code
const result = await wispgpt.explainCode(`
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n-1) + fibonacci(n-2);
}
`, {
  language: 'javascript' // Auto-detected if not specified
});

console.log(result.recipe);
// > analyze recursive function structure
// > handle base cases for 0 and 1
// > calculate fibonacci using recursive calls
// > return sum of previous two numbers

// Explain differences between code versions
const diffResult = await wispgpt.explainDiff(originalCode, modifiedCode);
console.log(diffResult.recipe);

🌐 Web Server

Start a local server with web interface:

npm start
# Opens http://localhost:3000

API Endpoints

# Explain code
curl -X POST http://localhost:3000/api/explain \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"hello\")", "provider": "openai"}'

# Explain diff
curl -X POST http://localhost:3000/api/diff \
  -H "Content-Type: application/json" \
  -d '{"originalCode": "old code", "modifiedCode": "new code"}'

# Get available providers and languages
curl http://localhost:3000/api/providers

⚙️ Configuration

Environment Variables

# OpenAI
OPENAI_API_KEY=your_key_here

# Anthropic (Claude)
ANTHROPIC_API_KEY=your_key_here

# Google (Gemini)
GEMINI_API_KEY=your_key_here

# Cloudflare Workers AI
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_API_TOKEN=your_token

Provider Configuration

Each provider supports different models and options:

// OpenAI
const wispgpt = new WispGPT({
  provider: 'openai',
  providerConfig: {
    apiKey: 'your-key',
    model: 'gpt-4-turbo-preview', // or 'gpt-3.5-turbo'
    baseURL: 'https://api.openai.com/v1' // optional
  }
});

// Anthropic
const wispgpt = new WispGPT({
  provider: 'anthropic',
  providerConfig: {
    apiKey: 'your-key',
    model: 'claude-3-sonnet-20240229' // or claude-3-haiku-20240307
  }
});

// Google Gemini
const wispgpt = new WispGPT({
  provider: 'gemini',
  providerConfig: {
    apiKey: 'your-key',
    model: 'gemini-1.5-pro' // or gemini-1.5-flash
  }
});

// Cloudflare Workers AI
const wispgpt = new WispGPT({
  provider: 'cloudflare',
  providerConfig: {
    accountId: 'your-account-id',
    apiToken: 'your-token',
    model: '@cf/meta/llama-3.1-8b-instruct' // or other available models
  }
});

🗣️ Supported Languages

WispGPT automatically detects and supports:

• Web: JavaScript, TypeScript, HTML, CSS
• Backend: Python, Java, C#, PHP, Ruby, Go, Rust
• Systems: C, C++, Swift, Kotlin, Scala
• Scripting: Shell/Bash, Lua
• Data: SQL, YAML, JSON

🔄 Cloudflare Workers Deployment

Deploy your own instance to Cloudflare Workers:

1. Setup Cloudflare Workers:

npm install -g wrangler
wrangler login

2. Configure wrangler.toml:

name = "wispgpt-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

[env.production]
vars = { ENVIRONMENT = "production" }

[[env.production.kv_namespaces]]
binding = "RECIPES"
id = "your-kv-namespace-id"

3. Deploy:

npm run build:worker

🧪 Testing

# Run unit tests
npm test

# Test with different providers
node examples/multiple-providers.js

# Test batch processing
node examples/batch-processing.js

📚 Advanced Usage

Batch Processing

const files = [
  { filename: 'auth.js', code: authCode, language: 'javascript' },
  { filename: 'models.py', code: pythonCode, language: 'python' }
];

const results = await wispgpt.explainMultiple(files);

Custom Prompts

// Advanced configuration with custom options
const result = await wispgpt.explainCode(code, {
  language: 'javascript',
  aiOptions: {
    temperature: 0.3, // More focused responses
    maxTokens: 500    // Shorter explanations
  }
});

Provider Switching

// Switch providers dynamically
wispgpt.setProvider('anthropic', {
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307' // Faster, cheaper model
});

🛠️ Development

Project Structure

wispgpt-code-explainer/
├── lib/
│   ├── providers/          # AI provider implementations
│   ├── core/              # Language detection, diff generation
│   ├── index.js           # Main library
│   └── server.js          # Web server
├── bin/
│   └── cli.js             # Command-line interface
├── examples/              # Usage examples
├── test/                  # Test files
├── src/                   # Cloudflare Worker source
└── public/                # Web interface assets

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run tests: npm test
5. Submit a pull request

Local Development

# Clone repository
git clone https://github.com/wispgpt/code-explainer.git
cd code-explainer

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Add your API keys to .env

# Run tests
npm test

# Start development server
npm run dev

🚨 Troubleshooting

Common Issues

API Key Errors

# Verify your API key is set
echo $OPENAI_API_KEY

# Run setup again
wispgpt setup

Language Detection Issues

# Specify language explicitly
wispgpt explain --file code.txt --language python

Rate Limits

• OpenAI: Check your usage limits and billing
• Anthropic: Claude has different rate limits per model
• Gemini: Free tier has daily limits
• Cloudflare: Generous free tier, but check Workers AI limits

Provider-Specific Notes

• OpenAI: Best overall quality, requires paid API access
• Anthropic: Excellent for complex code, good at following instructions
• Gemini: Fast and free tier available, good for simple explanations
• Cloudflare: Free tier available, models update frequently

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔗 Links

• Website - Try the online demo
• Documentation - Full documentation
• GitHub Issues - Bug reports and feature requests
• Discord - Community support

⭐ Show Your Support

If WispGPT helps you understand code better, please give it a star! ⭐

---

Made with 🍃 by the WispGPT team