@agentlify/mcp-server 2.0.0

package/docs/migration-openai.md

@@ -0,0 +1,383 @@
+# Migrating from OpenAI to Agentlify
+
+**Zero code changes required** - Keep using the OpenAI SDK with Agentlify's intelligent routing!
+
+---
+
+## Why Use Agentlify?
+
+✅ **40-60% cost savings** with intelligent model routing  
+✅ **Zero code changes** - just update SDK configuration  
+✅ **Automatic fallbacks** for improved reliability  
+✅ **100+ models** from OpenAI, Anthropic, Google, and more  
+✅ **Real-time cost tracking** with detailed analytics  
+✅ **Multi-provider access** through familiar OpenAI interface
+
+## Quick Comparison
+
+| Feature          | OpenAI Only             | Agentlify                     |
+| ---------------- | ----------------------- | ----------------------------- |
+| Cost             | High (single provider)  | 40-60% lower (auto-routing)   |
+| Reliability      | Single point of failure | Automatic fallbacks           |
+| Model Choice     | OpenAI models only      | 100+ models from 6+ providers |
+| Cost Tracking    | Manual                  | Real-time dashboard           |
+| Setup Time       | 5 minutes               | **2 minutes** (config only!)  |
+| **Code Changes** | N/A                     | **Zero!** Same SDK            |
+
+---
+
+## Migration Steps
+
+### Step 1: Create Agentlify Account & Router
+
+1. **Sign up** at [agentlify.app](https://agentlify.app)
+2. **Create a router** in the dashboard:
+   - Click "Create Router"
+   - Choose routing strategy (cost/quality/speed optimized)
+   - Router automatically gets access to all 100+ models
+3. **Get your API key** from Settings → API Keys (starts with `mp_`)
+4. **Copy your Router ID** from the router page
+
+### Step 2: Update OpenAI SDK Configuration
+
+**That's literally it!** Just change two config options:
+
+---
+
+## Python Migration
+
+### Before (Pure OpenAI):
+
+```python
+from openai import OpenAI
+
+client = OpenAI(api_key="sk-...")
+
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello!"}],
+    temperature=0.7
+)
+```
+
+### After (Agentlify):
+
+```python
+from openai import OpenAI  # Same import!
+
+# Only change these two lines:
+client = OpenAI(
+    api_key="mp_xxx",  # Your Agentlify API key
+    base_url="https://agentlify.co/api/router/your_router_id"
+)
+
+# Everything else stays exactly the same!
+response = client.chat.completions.create(
+    model="gpt-4",  # Optional - router optimizes automatically
+    messages=[{"role": "user", "content": "Hello!"}],
+    temperature=0.7
+)
+
+# NEW: Access Agentlify metadata
+print(f"Cost: ${response._meta.cost}")
+print(f"Model used: {response._meta.modelUsed}")
+print(f"Latency: {response._meta.latency}ms")
+```
+
+### What Changed:
+
+1. ✅ **`api_key`**: Use Agentlify key (`mp_xxx`) instead of OpenAI key
+2. ✅ **`base_url`**: Point to your router endpoint
+3. ✅ **That's it!** All other code works exactly the same
+
+---
+
+## JavaScript/TypeScript Migration
+
+### Before (Pure OpenAI):
+
+```javascript
+const { OpenAI } = require('openai');
+
+const client = new OpenAI({
+  apiKey: 'sk-...',
+});
+
+const response = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  temperature: 0.7,
+});
+```
+
+### After (Agentlify):
+
+```javascript
+const { OpenAI } = require('openai'); // Same import!
+
+// Only change these two lines:
+const client = new OpenAI({
+  apiKey: process.env.AGENTLIFY_API_KEY, // mp_xxx
+  baseURL: `https://agentlify.co/api/router/${process.env.AGENTLIFY_ROUTER_ID}`,
+});
+
+// Everything else stays exactly the same!
+const response = await client.chat.completions.create({
+  model: 'gpt-4', // Optional - router optimizes automatically
+  messages: [{ role: 'user', content: 'Hello!' }],
+  temperature: 0.7,
+});
+
+// NEW: Access Agentlify metadata
+console.log('Cost:', response._meta?.cost);
+console.log('Model used:', response._meta?.modelUsed);
+```
+
+### What Changed:
+
+1. ✅ **`apiKey`**: Use Agentlify key
+2. ✅ **`baseURL`**: Point to your router
+3. ✅ **That's it!** No other code changes needed
+
+---
+
+## Environment Variables
+
+Create a `.env` file:
+
+```bash
+# Agentlify credentials
+AGENTLIFY_API_KEY=mp_your_api_key_here
+AGENTLIFY_ROUTER_ID=your_router_id_here
+
+# Optional: Keep OpenAI as fallback
+OPENAI_API_KEY=sk_your_openai_key_here
+```
+
+---
+
+## Feature Parity
+
+**Everything works exactly the same:**
+
+| OpenAI Feature   | Agentlify Support  | Notes                       |
+| ---------------- | ------------------ | --------------------------- |
+| Chat Completions | ✅ Fully supported | Identical API               |
+| Streaming        | ✅ Fully supported | `stream: true` works        |
+| Function Calling | ✅ Fully supported | Same format                 |
+| Tool Calling     | ✅ Fully supported | Modern tools API            |
+| JSON Mode        | ✅ Fully supported | `response_format` supported |
+| Vision (GPT-4V)  | ✅ Fully supported | All vision models           |
+| Embeddings       | ✅ Fully supported | Multi-provider              |
+| System Prompts   | ✅ Fully supported | Identical behavior          |
+
+---
+
+## Streaming Example
+
+### Python:
+
+```python
+stream = client.chat.completions.create(
+    messages=[{"role": "user", "content": "Write a poem"}],
+    stream=True
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end='')
+```
+
+### JavaScript:
+
+```javascript
+const stream = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Write a poem' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+**Works exactly the same!**
+
+---
+
+## Function/Tool Calling Example
+
+```javascript
+const response = await client.chat.completions.create({
+  messages: [{ role: 'user', content: "What's the weather in NYC?" }],
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        description: 'Get current weather',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: { type: 'string' },
+          },
+          required: ['location'],
+        },
+      },
+    },
+  ],
+});
+
+// Works identically with Agentlify!
+```
+
+---
+
+## Cost Comparison
+
+### Example: 1M input + 500K output tokens using GPT-4
+
+| Provider                   | Monthly Cost     |
+| -------------------------- | ---------------- |
+| OpenAI Direct              | $100.00          |
+| Agentlify (cost-optimized) | **$45.00**       |
+| **Savings**                | **$55.00 (55%)** |
+
+### How Agentlify Saves Money:
+
+1. **Automatic routing** to cheapest suitable model
+2. **Model alternatives** (uses GPT-4-Turbo when appropriate)
+3. **Provider diversity** (Anthropic/Google when cheaper)
+4. **Real-time optimization** based on usage patterns
+
+---
+
+## Testing Your Migration
+
+### Use MCP `test_request` Tool:
+
+```
+User: "Test my router with: Hello, how are you?"
+
+AI Assistant:
+Response: "I'm doing great! How can I help you today?"
+Cost: $0.0008
+Model used: gpt-4o-mini
+Latency: 450ms
+```
+
+Returns full response with exact cost and performance metrics.
+
+---
+
+## Migration Checklist
+
+- [ ] Create Agentlify account
+- [ ] Create a router (cost/quality/speed optimized)
+- [ ] Get API key (`mp_xxx`)
+- [ ] Get Router ID from dashboard
+- [ ] Update `api_key` in your code
+- [ ] Update `base_url` / `baseURL` to router endpoint
+- [ ] Test with sample request
+- [ ] Monitor costs in dashboard
+- [ ] Deploy to production!
+
+**Total time: ~2 minutes**
+
+---
+
+## Common Questions
+
+### Q: Will my code break?
+
+**A:** No! The OpenAI SDK works identically. Just update config.
+
+### Q: What if Agentlify goes down?
+
+**A:** Routers have automatic fallbacks. If one model fails, it tries the next.
+
+### Q: Can I still use GPT-4?
+
+**A:** Yes! The router has access to all OpenAI models plus 100+ others.
+
+### Q: How do I track costs?
+
+**A:** Real-time dashboard at agentlify.app/dashboard + use the `get_usage_summary` MCP tool.
+
+### Q: What about rate limits?
+
+**A:** Agentlify spreads requests across providers, increasing your effective rate limit.
+
+### Q: Do I need to learn a new SDK?
+
+**A:** **No!** Keep using OpenAI SDK. Just change the config.
+
+---
+
+## Framework Integration
+
+### Works with everything that uses OpenAI SDK:
+
+**LangChain:**
+
+```python
+from langchain.chat_models import ChatOpenAI
+
+chat = ChatOpenAI(
+    openai_api_key="mp_xxx",
+    openai_api_base="https://agentlify.co/api/router/your_router_id"
+)
+```
+
+**LlamaIndex:**
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    api_key="mp_xxx",
+    api_base="https://agentlify.co/api/router/your_router_id"
+)
+```
+
+**Vercel AI SDK:**
+
+```typescript
+import { OpenAI } from 'ai';
+
+const config = {
+  apiKey: 'mp_xxx',
+  basePath: 'https://agentlify.co/api/router/your_router_id',
+};
+```
+
+---
+
+## Need Help?
+
+### Use the MCP `migrate_code` tool for automatic conversion:
+
+```
+User: "Migrate this OpenAI code: [paste your code]"
+
+AI Assistant:
+✅ Converted code
+✅ Estimated 45% cost savings
+✅ Next steps
+✅ Testing recommendations
+```
+
+---
+
+## Next Steps
+
+1. **Optimize further** - Use `optimize_router` to find additional savings
+2. **Monitor usage** - Use `get_usage_summary` for daily/weekly reports
+3. **Compare models** - Use `compare_models` to find the best fit
+4. **Generate code** - Use `generate_integration_code` for production setup
+
+---
+
+**Ready to save 40-60% on AI costs?** Start migrating now! 🚀
+
+**Key Takeaway:** You keep using the OpenAI SDK you know and love - just point it at Agentlify for intelligent routing and massive cost savings.

package/docs/pricing.md

@@ -0,0 +1,351 @@
+# Pricing & Billing
+
+Understanding Agentlify's pricing model.
+
+---
+
+## Overview
+
+Agentlify uses **pay-as-you-go** pricing - you only pay for what you use.
+
+**Key principle:** You pay for the **actual model used**, not a Agentlify markup. Our intelligent routing saves you 40-60% by choosing cheaper models automatically.
+
+---
+
+## How It Works
+
+### 1. Router Routes Your Request
+
+Your request goes to Agentlify router → Router selects best model → Request sent to that model
+
+### 2. You Pay Actual Model Cost
+
+- If router selects GPT-4o-mini: You pay GPT-4o-mini rates
+- If router selects Claude 3.5 Sonnet: You pay Claude rates
+- If router selects Gemini Pro: You pay Gemini rates
+
+### 3. No Agentlify Markup
+
+**$0** markup on model costs. You pay wholesale rates.
+
+### 4. Savings from Intelligent Routing
+
+Router automatically picks cheaper models → You save 40-60% vs. using premium models only
+
+---
+
+## Sample Model Pricing
+
+### Budget Models (Recommended for most tasks)
+
+| Model          | Input (per 1M tokens) | Output (per 1M tokens) |
+| -------------- | --------------------- | ---------------------- |
+| GPT-4o-mini    | $0.15                 | $0.60                  |
+| Claude 3 Haiku | $0.25                 | $1.25                  |
+| Gemini Flash   | $0.35                 | $1.05                  |
+
+### Mid-Tier Models
+
+| Model             | Input (per 1M tokens) | Output (per 1M tokens) |
+| ----------------- | --------------------- | ---------------------- |
+| GPT-4-Turbo       | $10.00                | $30.00                 |
+| Claude 3.5 Sonnet | $3.00                 | $15.00                 |
+| Gemini Pro        | $0.50                 | $1.50                  |
+
+### Premium Models
+
+| Model         | Input (per 1M tokens) | Output (per 1M tokens) |
+| ------------- | --------------------- | ---------------------- |
+| GPT-4         | $30.00                | $60.00                 |
+| Claude 3 Opus | $15.00                | $75.00                 |
+
+---
+
+## Real Cost Examples
+
+### Example 1: Customer Support Chatbot
+
+**Usage:**
+
+- 10,000 conversations/month
+- Avg 1,000 input + 500 output tokens per conversation
+
+**Cost with GPT-4 only:**
+
+```
+Input:  10M tokens × $30/1M = $300
+Output: 5M tokens × $60/1M  = $300
+Total: $600/month
+```
+
+**Cost with Agentlify (cost-optimized):**
+
+```
+70% GPT-4o-mini: $180 (10,500M tokens)
+25% GPT-4-Turbo: $75 (3,750M tokens)
+5% GPT-4: $30 (750M tokens)
+Total: $285/month
+```
+
+**Savings: $315/month (52%)**
+
+---
+
+### Example 2: Content Generation
+
+**Usage:**
+
+- 1,000 articles/month
+- Avg 500 input + 2,000 output tokens per article
+
+**Cost with Claude 3 Opus only:**
+
+```
+Input:  0.5M tokens × $15/1M = $7.50
+Output: 2M tokens × $75/1M   = $150
+Total: $157.50/month
+```
+
+**Cost with Agentlify (quality-optimized):**
+
+```
+60% Claude 3.5 Sonnet: $54 (1.2M output)
+30% GPT-4-Turbo: $18 (0.6M output)
+10% Claude Opus: $15 (0.2M output)
+Total: $87/month
+```
+
+**Savings: $70.50/month (45%)**
+
+---
+
+## Billing Model
+
+### Pay-As-You-Go (Default)
+
+- Purchase credits upfront
+- Credits deducted per request
+- Never expire
+- Top up anytime
+
+**Credit packages:**
+
+- $10 starter
+- $50 basic
+- $100 standard
+- $500+ enterprise
+
+### Auto-Refill
+
+Enable automatic credit top-ups:
+
+- Set low balance threshold (e.g., $10)
+- Set refill amount (e.g., $50)
+- Charged automatically when balance low
+- Never run out of credits
+
+**Setup via Dashboard or MCP:**
+
+```
+User: "Enable auto-refill with $50 when balance below $10"
+AI: ✅ Auto-refill configured
+```
+
+---
+
+## Subscription Plans (Optional)
+
+### Pro Plan - $49/month
+
+Includes:
+
+- $60 in credits (20% bonus)
+- Priority routing
+- Advanced analytics
+- Email support
+
+### Business Plan - $249/month
+
+Includes:
+
+- $325 in credits (30% bonus)
+- Dedicated router instances
+- Custom model selection
+- Priority support
+- SSO integration
+
+### Enterprise Plan - Custom
+
+Includes:
+
+- Custom credit amounts
+- SLA guarantees
+- Dedicated account manager
+- Custom integrations
+- On-premise options
+
+---
+
+## Credit Usage
+
+### Check Balance
+
+**Dashboard:** View balance in top-right corner
+
+**API:**
+
+```javascript
+const balance = await client.getBalance();
+console.log('Balance:', balance.credits);
+```
+
+**MCP Tool:**
+
+```
+User: "What's my Agentlify balance?"
+AI: Balance: $45.67 | Subscription: Pro | Used this month: $12.34
+```
+
+### Usage Tracking
+
+Every response includes cost metadata:
+
+```javascript
+const response = await client.chat.completions.create({
+  /*...*/
+});
+console.log('Request cost:', response._meta.cost); // e.g., 0.0008
+```
+
+---
+
+## Cost Control
+
+### 1. Set Budget Limits
+
+Configure router with monthly budget:
+
+```javascript
+const router = await createRouter({
+  name: 'my-router',
+  budget_limit: 100, // $100/month max
+});
+```
+
+### 2. Monitor Usage
+
+**Daily:** Check dashboard for cost trends  
+**Weekly:** Review model distribution  
+**Monthly:** Analyze savings vs. single-provider
+
+### 3. Cost Alerts
+
+Set up alerts in dashboard:
+
+- Daily spending > $X
+- Monthly approaching budget
+- Unusual cost spikes
+
+### 4. Use MCP Tools
+
+```
+User: "Show my usage for last 7 days"
+AI: Total: $45 | Avg per request: $0.0045 | Trending: -12%
+
+User: "Optimize my router"
+AI: Switch to GPT-4-Turbo → Save $25/month
+```
+
+---
+
+## Refunds & Credits
+
+### Credit Purchases
+
+- Non-refundable
+- Never expire
+- Transferable between routers
+
+### Subscription
+
+- Cancel anytime
+- Unused credits roll over
+- Prorated refunds available
+
+---
+
+## Enterprise Pricing
+
+For high-volume usage (>$1,000/month), contact sales for:
+
+- Custom pricing
+- Volume discounts
+- Reserved capacity
+- SLA guarantees
+- Dedicated support
+
+---
+
+## Free Tier
+
+**$5 free credits** for new accounts:
+
+- Test Agentlify
+- ~500-5,000 requests (depending on models)
+- No credit card required
+- Upgrade anytime
+
+---
+
+## Comparison vs. Direct Providers
+
+### Monthly cost for 10M input + 5M output tokens:
+
+| Provider                       | Cost           |
+| ------------------------------ | -------------- |
+| OpenAI Direct (GPT-4)          | $600           |
+| Anthropic Direct (Claude Opus) | $525           |
+| **Agentlify (Cost-Optimized)** | **$250**       |
+| **Savings**                    | **$350 (58%)** |
+
+---
+
+## Frequently Asked Questions
+
+### Q: Is there a monthly minimum?
+
+**A:** No minimum. Pay only for what you use.
+
+### Q: Do credits expire?
+
+**A:** No, credits never expire.
+
+### Q: Can I get a refund?
+
+**A:** Credits are non-refundable. Subscriptions can be cancelled anytime with prorated refunds.
+
+### Q: What payment methods?
+
+**A:** Credit card, debit card, ACH (enterprise).
+
+### Q: How do I track costs?
+
+**A:** Real-time dashboard + every API response includes cost metadata + MCP tools.
+
+### Q: Can I set spending limits?
+
+**A:** Yes, configure budget limits per router.
+
+---
+
+## Getting Started
+
+1. Sign up at [agentlify.app](https://agentlify.app)
+2. Get $5 free credits
+3. Create a router
+4. Start making requests
+5. Monitor savings in dashboard
+
+---
+
+**Bottom Line:** Pay wholesale model prices with no markup, save 40-60% through intelligent routing, and never worry about running out of credits with auto-refill!