@adityanair98/api-oracle 0.5.0

package/dist/updater/version-tracker.js

@@ -0,0 +1,50 @@
+/**
+ * Version tracker for API Oracle entries.
+ *
+ * Reads the current entryVersion from each entry and compares to a stored
+ * baseline to detect entries that have been updated since the last review.
+ *
+ * Exports: VersionSnapshot, VersionDiff, buildSnapshot, diffSnapshot
+ */
+// ─── Functions ────────────────────────────────────────────────────────────────
+/**
+ * Build a version snapshot from a list of entries.
+ */
+export function buildSnapshot(entries) {
+    const snapshot = {};
+    for (const entry of entries) {
+        snapshot[entry.slug] = entry.entryVersion;
+    }
+    return snapshot;
+}
+/**
+ * Diff a current entry list against a stored snapshot.
+ * Returns entries that are new or have an incremented version.
+ */
+export function diffSnapshot(entries, previousSnapshot) {
+    const diffs = [];
+    for (const entry of entries) {
+        const prev = previousSnapshot[entry.slug] ?? null;
+        if (prev === null) {
+            // New entry not in snapshot
+            diffs.push({
+                slug: entry.slug,
+                name: entry.name,
+                previousVersion: null,
+                currentVersion: entry.entryVersion,
+                changeType: "new",
+            });
+        }
+        else if (entry.entryVersion > prev) {
+            // Version was incremented
+            diffs.push({
+                slug: entry.slug,
+                name: entry.name,
+                previousVersion: prev,
+                currentVersion: entry.entryVersion,
+                changeType: "updated",
+            });
+        }
+    }
+    return diffs.sort((a, b) => a.slug.localeCompare(b.slug));
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Configuration — reads environment variables and provides typed defaults.
+ *
+ * Exports: config (singleton config object)
+ */
+export interface Config {
+    dbPath: string;
+    logLevel: string;
+    nodeEnv: string;
+}
+export declare const config: Config;

package/dist/utils/config.js

@@ -0,0 +1,13 @@
+/**
+ * Configuration — reads environment variables and provides typed defaults.
+ *
+ * Exports: config (singleton config object)
+ */
+function loadConfig() {
+    return {
+        dbPath: process.env["DB_PATH"] ?? "./data/api-oracle.db",
+        logLevel: process.env["LOG_LEVEL"] ?? "info",
+        nodeEnv: process.env["NODE_ENV"] ?? "development",
+    };
+}
+export const config = loadConfig();

package/dist/utils/logger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Simple structured logger — no external dependencies.
+ * Writes to stderr so MCP stdout stays clean for protocol messages.
+ *
+ * Exports: logger (default instance), createLogger
+ */
+declare function createLogger(namespace: string): {
+    debug: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+};
+export type Logger = ReturnType<typeof createLogger>;
+export { createLogger };
+export declare const logger: {
+    debug: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,32 @@
+/**
+ * Simple structured logger — no external dependencies.
+ * Writes to stderr so MCP stdout stays clean for protocol messages.
+ *
+ * Exports: logger (default instance), createLogger
+ */
+function formatEntry(entry) {
+    const base = `[${entry.timestamp}] [${entry.level.toUpperCase()}] ${entry.message}`;
+    if (entry.data !== undefined) {
+        return `${base} ${JSON.stringify(entry.data)}`;
+    }
+    return base;
+}
+function createLogger(namespace) {
+    function log(level, message, data) {
+        const entry = {
+            level,
+            message: namespace ? `[${namespace}] ${message}` : message,
+            timestamp: new Date().toISOString(),
+            data,
+        };
+        process.stderr.write(formatEntry(entry) + "\n");
+    }
+    return {
+        debug: (message, data) => log("debug", message, data),
+        info: (message, data) => log("info", message, data),
+        warn: (message, data) => log("warn", message, data),
+        error: (message, data) => log("error", message, data),
+    };
+}
+export { createLogger };
+export const logger = createLogger("api-oracle");

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@adityanair98/api-oracle",
+  "version": "0.5.0",
+  "description": "MCP server that finds, evaluates, and recommends the best API for any programming task",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "api-oracle": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "src/entries/",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "claude",
+    "api",
+    "recommendation",
+    "developer-tools",
+    "ai-tools"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc && cp -r src/dashboard/public dist/dashboard/public",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "validate": "tsx scripts/validate-entries.ts",
+    "seed": "tsx scripts/seed-db.ts",
+    "e2e": "tsx scripts/e2e-test.ts",
+    "analyze": "tsx scripts/scoring-analysis.ts",
+    "refresh-report": "tsx scripts/refresh-report.ts",
+    "lint-entries": "tsx scripts/lint-entries.ts",
+    "dashboard": "tsx src/dashboard/server.ts",
+    "dashboard:dev": "tsx watch src/dashboard/server.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "better-sqlite3": "12.6.2",
+    "express": "5.1.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
+    "@types/express": "5.0.3",
+    "@types/node": "25.3.0",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  }
+}

package/src/entries/ai/anthropic.json

@@ -0,0 +1,95 @@
+{
+  "name": "Anthropic API",
+  "slug": "anthropic",
+  "category": "ai",
+  "subcategory": "large-language-models",
+  "website": "https://www.anthropic.com/api",
+  "description": "Anthropic provides API access to the Claude family of AI models, known for exceptional reasoning, very long context windows (up to 200k tokens), strong instruction-following, and constitutional AI safety. Claude models excel at complex analysis, coding assistance, and nuanced writing tasks.",
+  "useCases": [
+    {
+      "task": "Analyze and reason over very long documents (up to 200k tokens)",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate code with high accuracy and explanations",
+      "fit": "perfect"
+    },
+    {
+      "task": "Build AI agents that use tools and follow complex instructions",
+      "fit": "perfect"
+    },
+    {
+      "task": "Process and analyze large codebases or legal documents",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate images or audio",
+      "fit": "partial"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at console.anthropic.com",
+      "Go to API Keys in the Console",
+      "Click 'Create Key' and give it a descriptive name",
+      "Add billing information to increase rate limits beyond free tier",
+      "Set ANTHROPIC_API_KEY environment variable"
+    ],
+    "envVarName": "ANTHROPIC_API_KEY",
+    "codeSnippet": "import Anthropic from '@anthropic-ai/sdk';\nconst anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": "Limited free tier with rate-limited test access",
+    "startingPrice": "claude-haiku-4-5: $0.80/M input, $4.00/M output",
+    "costPer": "claude-sonnet-4-6: $3.00/M input, $15.00/M output; claude-opus-4-6: $15.00/M input, $75.00/M output",
+    "pricingUrl": "https://www.anthropic.com/pricing"
+  },
+  "rateLimits": {
+    "tier": "build tier (default)",
+    "limit": "50 RPM, 40,000 input TPM for claude-sonnet on build tier",
+    "notes": "Rate limits increase as you spend more (usage tiers). Enterprise tier has custom limits with SLAs. Claude has a 200k token context window on all models.",
+    "retryStrategy": "Use exponential backoff for 529 (overloaded) and 429 (rate limit) errors; the Anthropic SDK includes automatic retry logic"
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @anthropic-ai/sdk",
+    "importStatement": "import Anthropic from '@anthropic-ai/sdk';",
+    "otherLanguages": ["python", "java", "go"]
+  },
+  "codeExamples": [
+    {
+      "title": "Basic message with Claude",
+      "language": "typescript",
+      "code": "import Anthropic from '@anthropic-ai/sdk';\n\nconst anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });\n\nconst message = await anthropic.messages.create({\n  model: 'claude-sonnet-4-6',\n  max_tokens: 1024,\n  messages: [\n    {\n      role: 'user',\n      content: 'Analyze this TypeScript code and identify potential bugs: ...',\n    },\n  ],\n});\n\nconst text = message.content[0];\nif (text.type === 'text') {\n  console.log(text.text);\n}\nconsole.log('Input tokens:', message.usage.input_tokens);\nconsole.log('Output tokens:', message.usage.output_tokens);",
+      "notes": "Always check message.content[0].type before accessing .text — content blocks can be 'text' or 'tool_use'. Use claude-haiku-4-5 for cost-sensitive tasks."
+    },
+    {
+      "title": "Tool use (function calling)",
+      "language": "typescript",
+      "code": "import Anthropic from '@anthropic-ai/sdk';\n\nconst anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });\n\nconst response = await anthropic.messages.create({\n  model: 'claude-sonnet-4-6',\n  max_tokens: 1024,\n  tools: [{\n    name: 'get_weather',\n    description: 'Get current weather for a location',\n    input_schema: {\n      type: 'object' as const,\n      properties: {\n        location: { type: 'string', description: 'City name' },\n      },\n      required: ['location'],\n    },\n  }],\n  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],\n});\n\nconst toolUse = response.content.find(block => block.type === 'tool_use');\nif (toolUse && toolUse.type === 'tool_use') {\n  console.log('Tool called:', toolUse.name);\n  console.log('Tool input:', toolUse.input);\n}",
+      "notes": "Tool use enables Claude to call your functions. After receiving a tool_use block, execute the function and return the result in a tool_result message to complete the conversation."
+    }
+  ],
+  "gotchas": [
+    "Claude's message format requires alternating user/assistant turns. You cannot send two consecutive user messages without an assistant message in between — this will throw a validation error.",
+    "The model returns content as an array of typed blocks (ContentBlock[]). Always check block.type before accessing block.text or block.input — using TypeScript's discriminated unions here prevents runtime errors.",
+    "Error code 529 ('API overloaded') is distinct from 429 (rate limit). Both require retry with backoff, but 529 means Anthropic's infrastructure is under high load, not that you exceeded your quota.",
+    "Extended thinking (beta feature) is not available on all models and significantly increases latency and cost. Only enable it for tasks that genuinely require deep multi-step reasoning.",
+    "Prompt caching can reduce costs by up to 90% for repeated large contexts (e.g., system prompts with long documents). Mark cacheable content with cache_control: { type: 'ephemeral' }."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime SLA on Enterprise plans",
+    "statusPageUrl": "https://status.anthropic.com",
+    "notes": "Anthropic's infrastructure has improved significantly. Occasional capacity issues during high-demand periods. Enterprise tier offers priority access."
+  },
+  "qualityScore": 9,
+  "qualityJustification": "Claude models lead on reasoning, instruction-following, and long-context tasks. Excellent TypeScript SDK, 200k context window, and strong safety properties. Pricing is competitive. Slight deductions vs OpenAI for smaller ecosystem and fewer modalities (no image gen).",
+  "alternatives": ["openai", "replicate"],
+  "complementary": ["uploadthing", "cloudinary"],
+  "bestFor": "Complex reasoning, long-document analysis, code generation, and AI agents with tools — especially where instruction-following quality matters",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-1"
+}

package/src/entries/ai/eleven-labs.json

@@ -0,0 +1,90 @@
+{
+  "name": "ElevenLabs",
+  "slug": "eleven-labs",
+  "category": "ai",
+  "subcategory": "voice-synthesis",
+  "website": "https://elevenlabs.io",
+  "description": "ElevenLabs provides AI voice generation with the most realistic text-to-speech available. Features include 3,000+ pre-made voices, voice cloning from audio samples, real-time voice streaming, and speech-to-speech (voice conversion). Used for audiobooks, video narration, accessibility, and conversational AI applications.",
+  "useCases": [
+    {
+      "task": "Generate realistic AI voiceover from text for video or audio content",
+      "fit": "perfect"
+    },
+    {
+      "task": "Add text-to-speech to an app with natural-sounding voices",
+      "fit": "perfect"
+    },
+    {
+      "task": "Clone a voice from audio samples for consistent narration",
+      "fit": "good"
+    },
+    {
+      "task": "Build a real-time conversational AI with voice output",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Create an ElevenLabs account at elevenlabs.io",
+      "Click your profile avatar in the top right",
+      "Go to Profile + API Key",
+      "Copy the API key shown",
+      "Set the ELEVENLABS_API_KEY environment variable"
+    ],
+    "envVarName": "ELEVENLABS_API_KEY",
+    "codeSnippet": "import { ElevenLabsClient } from 'elevenlabs';\n\nconst client = new ElevenLabsClient({\n  apiKey: process.env.ELEVENLABS_API_KEY,\n});"
+  },
+  "pricing": {
+    "model": "freemium",
+    "freeTier": "Free: 10,000 characters/month (~7 minutes of audio), 3 custom voices, non-commercial use only",
+    "startingPrice": "$5/month (Starter) for 30,000 characters/month with commercial use included",
+    "costPer": "Starter: $5/month for 30K chars; Creator: $22/month for 100K chars; Pro: $99/month for 500K chars",
+    "pricingUrl": "https://elevenlabs.io/pricing"
+  },
+  "rateLimits": {
+    "tier": "free tier",
+    "limit": "Free: 10,000 characters/month; API concurrency: 2 concurrent streams (free), 5 (Starter), 10 (Creator); character limits reset monthly",
+    "notes": "Character limits are strict hard caps — the API returns an error when the monthly quota is exhausted. Generation latency depends on voice model: Eleven Multilingual v2 takes 2-5s; Eleven Flash v2.5 (optimized for real-time) takes under 0.5s to first byte. Use streaming for real-time applications.",
+    "retryStrategy": "Retry on 429 with exponential backoff. For real-time streaming, implement reconnect logic on stream interruption with an increasing delay (start at 1s, cap at 30s)."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact elevenlabs",
+    "importStatement": "import { ElevenLabsClient } from 'elevenlabs';",
+    "otherLanguages": ["python"]
+  },
+  "codeExamples": [
+    {
+      "title": "Generate speech from text and save to file",
+      "language": "typescript",
+      "code": "import { ElevenLabsClient } from 'elevenlabs';\nimport fs from 'fs';\nimport path from 'path';\n\nconst client = new ElevenLabsClient({\n  apiKey: process.env.ELEVENLABS_API_KEY,\n});\n\nasync function textToSpeech(\n  text: string,\n  voiceId: string,\n  outputPath: string\n): Promise<void> {\n  const audio = await client.textToSpeech.convert(voiceId, {\n    text,\n    model_id: 'eleven_multilingual_v2',\n    voice_settings: {\n      stability: 0.5,\n      similarity_boost: 0.75,\n    },\n    output_format: 'mp3_44100_128',\n  });\n\n  // audio is a ReadableStream — collect all chunks into a Buffer\n  const chunks: Buffer[] = [];\n  for await (const chunk of audio) {\n    chunks.push(Buffer.from(chunk));\n  }\n  const audioBuffer = Buffer.concat(chunks);\n\n  fs.writeFileSync(outputPath, audioBuffer);\n  console.log(`Audio saved to ${outputPath} (${audioBuffer.length} bytes)`);\n}\n\n// 'Rachel' is a popular pre-made ElevenLabs voice\nconst RACHEL_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';\n\nawait textToSpeech(\n  'Hello! This is a test of the ElevenLabs text-to-speech API.',\n  RACHEL_VOICE_ID,\n  path.join(process.cwd(), 'output.mp3')\n);",
+      "notes": "The convert() method returns a ReadableStream. Collect chunks in a loop before writing to disk. Use eleven_flash_v2_5 instead of eleven_multilingual_v2 for lower-latency applications — it generates audio ~10x faster with slightly lower quality."
+    },
+    {
+      "title": "Stream audio in real-time for low-latency playback",
+      "language": "typescript",
+      "code": "import { ElevenLabsClient } from 'elevenlabs';\nimport { Writable } from 'stream';\n\nconst client = new ElevenLabsClient({\n  apiKey: process.env.ELEVENLABS_API_KEY,\n});\n\nasync function streamSpeechToOutput(\n  text: string,\n  voiceId: string,\n  outputStream: Writable\n): Promise<void> {\n  const audioStream = await client.textToSpeech.stream(voiceId, {\n    text,\n    model_id: 'eleven_flash_v2_5', // Use Flash model for lowest latency\n    voice_settings: {\n      stability: 0.5,\n      similarity_boost: 0.75,\n    },\n    output_format: 'pcm_16000', // PCM for real-time audio pipelines\n  });\n\n  return new Promise<void>((resolve, reject) => {\n    audioStream.on('data', (chunk: Buffer) => {\n      outputStream.write(chunk);\n    });\n\n    audioStream.on('end', () => {\n      outputStream.end();\n      resolve();\n    });\n\n    audioStream.on('error', (err: Error) => {\n      reject(err);\n    });\n  });\n}\n\n// Example: stream to stdout (pipe to a media player like ffplay)\nconst RACHEL_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';\n\nawait streamSpeechToOutput(\n  'This audio streams in real-time with sub-500ms latency to first byte.',\n  RACHEL_VOICE_ID,\n  process.stdout\n);",
+      "notes": "The Flash v2.5 model achieves under 500ms latency to first audio byte — suitable for conversational AI. Use pcm_16000 format when piping to an audio pipeline. For browser playback, use mp3_44100_128 and create a MediaSource object to append chunks as they arrive."
+    }
+  ],
+  "gotchas": [
+    "Free plan audio is explicitly marked as non-commercial in ElevenLabs' terms of service — you cannot use free tier generated audio in commercial products. Any app that generates revenue (including ad-supported free apps) requires a paid plan starting at $5/month.",
+    "Voice cloning requires a minimum of 1 minute of clean audio samples. Background noise, music, or multiple speakers significantly degrades clone quality. Record in a quiet environment with a good microphone, and avoid audio that has been compressed with heavy codecs (use WAV or high-bitrate MP3).",
+    "ElevenLabs returns audio as a binary stream (ArrayBuffer chunks). In Node.js, collect chunks into a Buffer array and concatenate before writing to a file. In browsers, create a Blob from received chunks and generate a Blob URL for playback. The default output format is MP3; specify output_format explicitly to get PCM or WebM for lower-latency streaming scenarios.",
+    "Character limits count ALL characters in the text string, including spaces, punctuation, and SSML markup tags. A 5,000-character essay consumes 5,000 of your monthly quota. SSML tags like <break time='1s'/> count toward the limit too. Plan quota usage carefully if your app generates long-form content."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime (Business plan and above)",
+    "statusPageUrl": "https://status.elevenlabs.io",
+    "notes": "Globally distributed infrastructure with generally high availability. Occasional latency spikes during peak hours. The streaming API is production-ready. Business plan includes a 99.9% uptime SLA with dedicated support."
+  },
+  "qualityScore": 9,
+  "qualityJustification": "Best-in-class AI voice quality — ElevenLabs voices are noticeably more natural than competitors including Amazon Polly and Google Text-to-Speech. The Flash v2.5 streaming model is particularly impressive for real-time conversational applications. 3,000+ pre-made voices and instant voice cloning make it versatile. Main friction: non-commercial restriction on free tier and strict character caps, but the voice quality justifies the cost for any serious audio application.",
+  "alternatives": ["resemble-ai"],
+  "complementary": ["openai", "anthropic", "cloudinary", "mux"],
+  "bestFor": "AI-generated voice narration and text-to-speech with the most natural-sounding output — audiobooks, video narration, accessibility features, and real-time conversational AI",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-4"
+}

package/src/entries/ai/openai.json

@@ -0,0 +1,95 @@
+{
+  "name": "OpenAI API",
+  "slug": "openai",
+  "category": "ai",
+  "subcategory": "large-language-models",
+  "website": "https://platform.openai.com",
+  "description": "OpenAI provides API access to GPT-4, GPT-4o, and other frontier AI models for text generation, reasoning, image generation, embeddings, and more. It is the most widely adopted AI API with extensive documentation, community resources, and a broad feature set.",
+  "useCases": [
+    {
+      "task": "Generate text using GPT-4 or GPT-4o language models",
+      "fit": "perfect"
+    },
+    {
+      "task": "Build a conversational AI chatbot",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate embeddings for semantic search or RAG",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate images with DALL-E",
+      "fit": "good"
+    },
+    {
+      "task": "Transcribe audio to text with Whisper",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "bearer_token",
+    "setupSteps": [
+      "Sign up at platform.openai.com",
+      "Go to API Keys under your account settings",
+      "Click 'Create new secret key'",
+      "Add billing information (required even for free trial)",
+      "Set OPENAI_API_KEY environment variable"
+    ],
+    "envVarName": "OPENAI_API_KEY",
+    "codeSnippet": "import OpenAI from 'openai';\nconst openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": "No free tier (free trial credits expire); pay per token",
+    "startingPrice": "gpt-4o-mini: $0.15/M input tokens, $0.60/M output tokens",
+    "costPer": "gpt-4o: $2.50/M input, $10.00/M output; gpt-4o-mini: $0.15/M input, $0.60/M output",
+    "pricingUrl": "https://openai.com/pricing"
+  },
+  "rateLimits": {
+    "tier": "tier 1 (default)",
+    "limit": "500 RPM, 30,000 TPM for gpt-4o on Tier 1",
+    "notes": "Rate limits scale with spend tier (Tier 1-5). Limits are per model, not account-wide. Higher tiers unlock higher throughput automatically as you spend more.",
+    "retryStrategy": "Use exponential backoff with jitter for 429 errors; the openai SDK has built-in retry logic via maxRetries option"
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact openai",
+    "importStatement": "import OpenAI from 'openai';",
+    "otherLanguages": ["python", "java", "go", "dotnet"]
+  },
+  "codeExamples": [
+    {
+      "title": "Chat completion with GPT-4o",
+      "language": "typescript",
+      "code": "import OpenAI from 'openai';\n\nconst openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });\n\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4o',\n  messages: [\n    { role: 'system', content: 'You are a helpful assistant.' },\n    { role: 'user', content: 'Explain quantum entanglement in one paragraph.' },\n  ],\n  max_tokens: 500,\n  temperature: 0.7,\n});\n\nconsole.log(response.choices[0]?.message.content);\nconsole.log('Tokens used:', response.usage?.total_tokens);",
+      "notes": "Always track token usage for cost monitoring. Use gpt-4o-mini for cost-sensitive applications — it's ~17x cheaper for most tasks."
+    },
+    {
+      "title": "Generate embeddings for semantic search",
+      "language": "typescript",
+      "code": "import OpenAI from 'openai';\n\nconst openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });\n\nconst response = await openai.embeddings.create({\n  model: 'text-embedding-3-small',\n  input: 'The quick brown fox jumps over the lazy dog',\n  encoding_format: 'float',\n});\n\nconst embedding = response.data[0]?.embedding;\nconsole.log('Embedding dimensions:', embedding?.length); // 1536 for text-embedding-3-small",
+      "notes": "text-embedding-3-small is the recommended embedding model: $0.02/M tokens and 1536 dimensions. Use for RAG, similarity search, and clustering."
+    }
+  ],
+  "gotchas": [
+    "Token costs accumulate quickly with large contexts. Always set max_tokens and monitor usage. A 128k context window doesn't mean you should always use it — long prompts are expensive.",
+    "API keys are scoped to an organization. If you work with multiple projects/clients, use separate organizations or project-level API keys to isolate billing and prevent accidental cross-contamination.",
+    "Model names change and older models get deprecated. Pin to specific model versions (e.g., 'gpt-4o-2024-08-06') in production to avoid unexpected capability changes from model updates.",
+    "The free trial credits expire after a short time period. You must add billing information to continue using the API after the trial.",
+    "Streaming responses require different handling — use openai.chat.completions.stream() and handle the async iterator pattern."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "No published SLA for standard tier; Enterprise plan offers SLA",
+    "statusPageUrl": "https://status.openai.com",
+    "notes": "OpenAI has had occasional outages and capacity issues during high-demand periods. For production applications, implement fallback models or providers."
+  },
+  "qualityScore": 9,
+  "qualityJustification": "Most capable models available, largest ecosystem, best-in-class TypeScript SDK, and the most documented AI API. Slight deductions for no free tier, occasional reliability issues, and usage-based costs that can surprise teams without monitoring.",
+  "alternatives": ["anthropic", "deepgram", "replicate", "stability-ai"],
+  "complementary": ["uploadthing", "cloudinary"],
+  "bestFor": "General-purpose LLM tasks including chat, reasoning, embeddings, and image generation with the broadest model selection",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-1"
+}

package/src/entries/ai/replicate.json

@@ -0,0 +1,87 @@
+{
+  "name": "Replicate",
+  "slug": "replicate",
+  "category": "ai",
+  "subcategory": "ml-model-hosting",
+  "website": "https://replicate.com",
+  "description": "Replicate is a cloud platform for running open-source machine learning models via API — including image generation (Stable Diffusion, FLUX), video generation, audio models, LLMs, and more. It abstracts away all GPU infrastructure, letting developers run state-of-the-art models with a single API call and pay only for the compute time used.",
+  "useCases": [
+    {
+      "task": "Generate images from text prompts using Stable Diffusion or FLUX",
+      "fit": "perfect"
+    },
+    {
+      "task": "Run open-source LLMs (Llama, Mistral, etc.) via API",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate or edit video with AI models",
+      "fit": "perfect"
+    },
+    {
+      "task": "Remove image backgrounds, upscale images, or apply style transfer",
+      "fit": "perfect"
+    },
+    {
+      "task": "Fine-tune and host a custom ML model on GPU infrastructure",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at replicate.com",
+      "Go to Account Settings > API tokens",
+      "Create a new API token",
+      "Set REPLICATE_API_TOKEN environment variable"
+    ],
+    "envVarName": "REPLICATE_API_TOKEN",
+    "codeSnippet": "import Replicate from 'replicate';\nconst replicate = new Replicate({ auth: process.env.REPLICATE_API_TOKEN! });"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": "No free tier; new accounts get a small credit to get started",
+    "startingPrice": "Pay-per-second of GPU compute; starts from ~$0.000225/sec (CPU) to ~$0.0008/sec (T4 GPU)",
+    "costPer": "Varies by model and hardware: Stable Diffusion SDXL: ~$0.0046/image; Llama 3 70B: ~$0.00065/1M tokens; FLUX Pro: ~$0.055/image",
+    "pricingUrl": "https://replicate.com/pricing"
+  },
+  "rateLimits": {
+    "tier": "default",
+    "limit": "No hard rate limit on predictions; concurrent predictions limited by account tier",
+    "notes": "Cold starts can add 10-60 seconds to the first prediction on a model if no warm instances are running. Use the 'warmup' feature or schedule predictions to keep instances warm for latency-sensitive apps.",
+    "retryStrategy": "Implement polling with exponential backoff for prediction status checks. Predictions can be long-running — use webhooks instead of polling for better reliability in production."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact replicate",
+    "importStatement": "import Replicate from 'replicate';",
+    "otherLanguages": ["python", "go", "elixir"]
+  },
+  "codeExamples": [
+    {
+      "title": "Generate an image with FLUX",
+      "language": "typescript",
+      "code": "import Replicate from 'replicate';\n\nconst replicate = new Replicate({\n  auth: process.env.REPLICATE_API_TOKEN!,\n});\n\n// Run FLUX Schnell (fast, good quality)\nconst output = await replicate.run(\n  'black-forest-labs/flux-schnell',\n  {\n    input: {\n      prompt: 'A serene Japanese garden with cherry blossoms, golden hour, photorealistic',\n      num_outputs: 1,\n      aspect_ratio: '16:9',\n      output_format: 'webp',\n      output_quality: 90,\n    },\n  }\n) as string[];\n\nconst imageUrl = output[0];\nconsole.log('Generated image:', imageUrl);\n\n// For streaming output (e.g., LLM text generation)\nfor await (const event of replicate.stream('meta/meta-llama-3-8b-instruct', {\n  input: { prompt: 'Write a haiku about code reviews.' },\n})) {\n  process.stdout.write(String(event));\n}",
+      "notes": "The output type varies by model — image models return URL arrays, LLMs return strings or streams. Always check the model's schema on replicate.com for the exact input/output shape. Output URLs expire after 24 hours — save images to your own storage."
+    }
+  ],
+  "gotchas": [
+    "Output files (images, audio, video) are hosted by Replicate on temporary URLs that expire after 24 hours. You must download and store the output to your own storage (S3, Cloudinary, etc.) immediately after generation if you need persistent access.",
+    "Cold starts are a real problem for user-facing latency. If a model hasn't been run recently, the first prediction waits for a GPU instance to start and load the model weights — this can take 30-60+ seconds for large models. Use `replicate.deployments` for dedicated endpoints that stay warm.",
+    "Model versions can be deprecated or removed by the community. Hard-coding a specific model version string (e.g., `owner/model:sha256hash`) pins to that exact version, preventing breaking changes. Always pin to a version, not just the model name.",
+    "Cost can spike unexpectedly with video generation models, which consume minutes of GPU time per second of video. Always set spending limits in your Replicate account and test with short durations before generating long videos."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime for the API; individual model availability varies",
+    "statusPageUrl": "https://replicate.com/status",
+    "notes": "Replicate's API and core infrastructure are reliable. Individual model availability can vary — community models may be deprecated. Use official or partner models for production workloads."
+  },
+  "qualityScore": 8,
+  "qualityJustification": "The easiest way to run any open-source ML model without managing GPU infrastructure. Exceptional breadth of available models (thousands), great TypeScript SDK, and transparent per-second pricing. The main limitations are cold starts for user-facing apps and no persistent storage for outputs. Ideal for prototyping and production ML workloads that don't need sub-second latency.",
+  "alternatives": ["openai", "anthropic", "resemble-ai", "stability-ai"],
+  "complementary": ["cloudinary", "uploadthing", "supabase", "openai", "deepgram"],
+  "bestFor": "Running open-source ML models (image generation, LLMs, video, audio) via API without managing GPU infrastructure",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-2"
+}