qualia-framework 2.2.0 → 2.4.0

package/framework/skills/openrouter-agent/SKILL.md

@@ -0,0 +1,922 @@
+---
+name: openrouter-agent
+description: "Build AI agents and chatbots using OpenRouter API — model selection, streaming, tool/function calling, cost-aware model switching, error handling, and provider failover. Use this skill whenever the user says 'build AI agent', 'build chatbot', 'openrouter', 'AI chat', 'LLM integration', or wants to integrate any LLM into a project. Also trigger when code imports from openrouter, or user mentions model selection, AI streaming, or chat endpoints."
+tags: [ai-agent, openrouter, llm, chatbot, streaming]
+---
+
+# OpenRouter Agent Builder
+
+Build AI agents and chatbots using OpenRouter as the unified LLM gateway. One API key, every model.
+
+**Announce at start:** "Activating OpenRouter agent builder. Let me set up your AI chat integration."
+
+## Why OpenRouter
+
+- Single API key for Claude, GPT-4o, Mistral, Llama, Gemini, and 200+ models
+- OpenAI SDK compatible — just swap `baseURL` and `apiKey`
+- Automatic failover between providers
+- Usage tracking and cost management built-in
+- No vendor lock-in — switch models with one string change
+
+## 1. API Setup
+
+### Base Configuration
+
+```
+Base URL:   https://openrouter.ai/api/v1
+Auth:       Bearer $OPENROUTER_API_KEY
+Headers:    HTTP-Referer: https://yoursite.com
+            X-Title: YourAppName
+```
+
+### Environment Variable
+
+```env
+# Server-side ONLY — never prefix with NEXT_PUBLIC_
+OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+### OpenAI SDK Compatibility
+
+```typescript
+// lib/openrouter.ts
+import OpenAI from 'openai';
+
+export const openrouter = new OpenAI({
+  baseURL: 'https://openrouter.ai/api/v1',
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  defaultHeaders: {
+    'HTTP-Referer': process.env.NEXT_PUBLIC_SITE_URL || 'https://yoursite.com',
+    'X-Title': process.env.NEXT_PUBLIC_APP_NAME || 'YourApp',
+  },
+});
+```
+
+## 2. Model Selection Guide
+
+| Use Case | Model | Why | Cost (in/out per M tokens) |
+|----------|-------|-----|----------------------------|
+| General chat | `anthropic/claude-sonnet-4-20250514` | Best balance of quality and cost | $3 / $15 |
+| Complex reasoning | `anthropic/claude-opus-4-20250514` | Most capable, deep analysis | $15 / $75 |
+| Fast / cheap | `mistralai/mistral-small-latest` | Low latency, low cost | $0.1 / $0.3 |
+| Code generation | `anthropic/claude-sonnet-4-20250514` | Best at code tasks | $3 / $15 |
+| Long context | `google/gemini-2.0-flash-001` | 1M token context window | $0.1 / $0.4 |
+| Vision / multimodal | `anthropic/claude-sonnet-4-20250514` | Image understanding + reasoning | $3 / $15 |
+| Budget chat | `meta-llama/llama-3.3-70b-instruct` | Open source, very cheap | $0.13 / $0.20 |
+| Summarization | `mistralai/mistral-small-latest` | Fast, good at extraction | $0.1 / $0.3 |
+
+### Model Selection Constants
+
+```typescript
+// lib/ai/models.ts
+export const MODELS = {
+  // Primary
+  SMART: 'anthropic/claude-sonnet-4-20250514',
+  POWERFUL: 'anthropic/claude-opus-4-20250514',
+  FAST: 'mistralai/mistral-small-latest',
+  LONG_CONTEXT: 'google/gemini-2.0-flash-001',
+  BUDGET: 'meta-llama/llama-3.3-70b-instruct',
+} as const;
+
+export type ModelId = (typeof MODELS)[keyof typeof MODELS];
+```
+
+## 3. Basic Integration (Next.js + Vercel AI SDK)
+
+### Install Dependencies
+
+```bash
+npm install ai openai zod
+```
+
+### Streaming Chat API Route
+
+```typescript
+// app/api/chat/route.ts
+import { streamText } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const openrouter = createOpenAI({
+  baseURL: 'https://openrouter.ai/api/v1',
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  headers: {
+    'HTTP-Referer': process.env.NEXT_PUBLIC_SITE_URL || 'https://yoursite.com',
+    'X-Title': process.env.NEXT_PUBLIC_APP_NAME || 'YourApp',
+  },
+});
+
+const RequestSchema = z.object({
+  messages: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+  })).min(1),
+  model: z.string().optional(),
+});
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const parsed = RequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return Response.json({ error: parsed.error.flatten() }, { status: 400 });
+  }
+
+  const { messages, model } = parsed.data;
+
+  const result = streamText({
+    model: openrouter(model || 'anthropic/claude-sonnet-4-20250514'),
+    system: `You are a helpful assistant. Be concise and accurate.`,
+    messages,
+    maxTokens: 4096,
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+### Client-Side Chat UI (React)
+
+```typescript
+// app/chat/page.tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export default function ChatPage() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <div>
+      <div>
+        {messages.map((msg) => (
+          <div key={msg.id}>
+            <strong>{msg.role}:</strong> {msg.content}
+          </div>
+        ))}
+      </div>
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### System Prompt Management
+
+```typescript
+// lib/ai/prompts.ts
+
+export function buildSystemPrompt(context: {
+  agentName: string;
+  agentRole: string;
+  instructions: string[];
+  constraints?: string[];
+}): string {
+  const lines = [
+    `You are ${context.agentName}, ${context.agentRole}.`,
+    '',
+    '## Instructions',
+    ...context.instructions.map(i => `- ${i}`),
+  ];
+
+  if (context.constraints?.length) {
+    lines.push('', '## Constraints', ...context.constraints.map(c => `- ${c}`));
+  }
+
+  return lines.join('\n');
+}
+```
+
+## 4. Tool / Function Calling
+
+### Define Tools
+
+```typescript
+// lib/ai/tools.ts
+import { tool } from 'ai';
+import { z } from 'zod';
+
+export const weatherTool = tool({
+  description: 'Get the current weather for a location',
+  parameters: z.object({
+    city: z.string().describe('The city name'),
+    country: z.string().optional().describe('ISO country code'),
+  }),
+  execute: async ({ city, country }) => {
+    // Replace with actual weather API call
+    const response = await fetch(
+      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}${country ? `,${country}` : ''}`
+    );
+    const data = await response.json();
+    return {
+      temperature: data.current.temp_c,
+      condition: data.current.condition.text,
+      humidity: data.current.humidity,
+    };
+  },
+});
+
+export const searchDatabaseTool = tool({
+  description: 'Search the knowledge base for relevant information',
+  parameters: z.object({
+    query: z.string().describe('The search query'),
+    limit: z.number().optional().default(5).describe('Max results'),
+  }),
+  execute: async ({ query, limit }) => {
+    const { createClient } = await import('@/lib/supabase/server');
+    const supabase = await createClient();
+
+    const { data, error } = await supabase
+      .from('knowledge_base')
+      .select('title, content')
+      .textSearch('content', query)
+      .limit(limit);
+
+    if (error) throw error;
+    return data;
+  },
+});
+```
+
+### API Route with Tools
+
+```typescript
+// app/api/chat/route.ts (with tools)
+import { streamText } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { weatherTool, searchDatabaseTool } from '@/lib/ai/tools';
+
+const openrouter = createOpenAI({
+  baseURL: 'https://openrouter.ai/api/v1',
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  headers: {
+    'HTTP-Referer': process.env.NEXT_PUBLIC_SITE_URL || 'https://yoursite.com',
+    'X-Title': process.env.NEXT_PUBLIC_APP_NAME || 'YourApp',
+  },
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openrouter('anthropic/claude-sonnet-4-20250514'),
+    system: 'You are a helpful assistant with access to tools. Use them when needed.',
+    messages,
+    tools: {
+      weather: weatherTool,
+      searchDatabase: searchDatabaseTool,
+    },
+    maxSteps: 5, // Allow up to 5 tool call rounds
+    maxTokens: 4096,
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+### Manual Tool Calling (without Vercel AI SDK)
+
+```typescript
+// lib/ai/tool-handler.ts
+import { openrouter } from '@/lib/openrouter';
+
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+export async function chatWithTools(
+  messages: Array<{ role: string; content: string }>,
+  tools: ToolDefinition[],
+  model = 'anthropic/claude-sonnet-4-20250514',
+  maxRounds = 5,
+) {
+  const openaiTools = tools.map(t => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }));
+
+  let currentMessages = [...messages];
+
+  for (let round = 0; round < maxRounds; round++) {
+    const response = await openrouter.chat.completions.create({
+      model,
+      messages: currentMessages,
+      tools: openaiTools,
+      max_tokens: 4096,
+    });
+
+    const choice = response.choices[0];
+
+    if (choice.finish_reason !== 'tool_calls' || !choice.message.tool_calls?.length) {
+      // No more tool calls — return the final response
+      return choice.message.content;
+    }
+
+    // Add assistant message with tool calls
+    currentMessages.push(choice.message as never);
+
+    // Execute each tool call
+    for (const toolCall of choice.message.tool_calls) {
+      const tool = tools.find(t => t.name === toolCall.function.name);
+      if (!tool) {
+        currentMessages.push({
+          role: 'tool',
+          content: JSON.stringify({ error: `Unknown tool: ${toolCall.function.name}` }),
+          tool_call_id: toolCall.id,
+        } as never);
+        continue;
+      }
+
+      try {
+        const args = JSON.parse(toolCall.function.arguments);
+        const result = await tool.execute(args);
+        currentMessages.push({
+          role: 'tool',
+          content: JSON.stringify(result),
+          tool_call_id: toolCall.id,
+        } as never);
+      } catch (error) {
+        currentMessages.push({
+          role: 'tool',
+          content: JSON.stringify({ error: String(error) }),
+          tool_call_id: toolCall.id,
+        } as never);
+      }
+    }
+  }
+
+  // Exceeded max rounds — get final response without tools
+  const final = await openrouter.chat.completions.create({
+    model,
+    messages: currentMessages,
+    max_tokens: 4096,
+  });
+
+  return final.choices[0].message.content;
+}
+```
+
+## 5. Cost-Aware Model Switching
+
+### Smart Router
+
+```typescript
+// lib/ai/router.ts
+import { MODELS, type ModelId } from './models';
+
+interface RoutingContext {
+  messageLength: number;
+  hasImages: boolean;
+  conversationTurns: number;
+  taskType: 'chat' | 'code' | 'analysis' | 'summarize';
+  budgetCentsRemaining?: number;
+}
+
+// Cost per 1K tokens (input + output estimate)
+const MODEL_COST_PER_1K: Record<ModelId, number> = {
+  [MODELS.POWERFUL]: 0.090,   // ~$90/M combined
+  [MODELS.SMART]: 0.018,      // ~$18/M combined
+  [MODELS.FAST]: 0.0004,      // ~$0.4/M combined
+  [MODELS.LONG_CONTEXT]: 0.0005,
+  [MODELS.BUDGET]: 0.00033,
+};
+
+export function selectModel(ctx: RoutingContext): ModelId {
+  // Budget-constrained: use cheapest model
+  if (ctx.budgetCentsRemaining !== undefined && ctx.budgetCentsRemaining < 5) {
+    return MODELS.FAST;
+  }
+
+  // Long input: use long context model
+  if (ctx.messageLength > 50_000) {
+    return MODELS.LONG_CONTEXT;
+  }
+
+  // Complex analysis: use the most capable model
+  if (ctx.taskType === 'analysis' && ctx.conversationTurns > 3) {
+    return MODELS.POWERFUL;
+  }
+
+  // Code generation: Sonnet is best
+  if (ctx.taskType === 'code') {
+    return MODELS.SMART;
+  }
+
+  // Short simple queries: use fast model
+  if (ctx.messageLength < 200 && ctx.conversationTurns < 2) {
+    return MODELS.FAST;
+  }
+
+  // Default: Sonnet (best balance)
+  return MODELS.SMART;
+}
+```
+
+### Token Budget Tracker
+
+```typescript
+// lib/ai/budget.ts
+
+interface UsageRecord {
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  costCents: number;
+  timestamp: Date;
+}
+
+export class BudgetTracker {
+  private usage: UsageRecord[] = [];
+  private budgetCents: number;
+
+  constructor(budgetCents: number) {
+    this.budgetCents = budgetCents;
+  }
+
+  record(model: string, promptTokens: number, completionTokens: number) {
+    const costCents = this.calculateCost(model, promptTokens, completionTokens);
+    this.usage.push({
+      model,
+      promptTokens,
+      completionTokens,
+      costCents,
+      timestamp: new Date(),
+    });
+    return costCents;
+  }
+
+  get remaining(): number {
+    const spent = this.usage.reduce((sum, u) => sum + u.costCents, 0);
+    return Math.max(0, this.budgetCents - spent);
+  }
+
+  get spent(): number {
+    return this.usage.reduce((sum, u) => sum + u.costCents, 0);
+  }
+
+  private calculateCost(model: string, promptTokens: number, completionTokens: number): number {
+    // Costs in dollars per million tokens -> convert to cents
+    const rates: Record<string, { input: number; output: number }> = {
+      'anthropic/claude-opus-4-20250514': { input: 15, output: 75 },
+      'anthropic/claude-sonnet-4-20250514': { input: 3, output: 15 },
+      'mistralai/mistral-small-latest': { input: 0.1, output: 0.3 },
+      'google/gemini-2.0-flash-001': { input: 0.1, output: 0.4 },
+      'meta-llama/llama-3.3-70b-instruct': { input: 0.13, output: 0.20 },
+    };
+
+    const rate = rates[model] || { input: 3, output: 15 }; // Default to Sonnet pricing
+    const inputCost = (promptTokens / 1_000_000) * rate.input * 100; // dollars -> cents
+    const outputCost = (completionTokens / 1_000_000) * rate.output * 100;
+    return inputCost + outputCost;
+  }
+}
+```
+
+### Failover Chain
+
+```typescript
+// lib/ai/failover.ts
+import { openrouter } from '@/lib/openrouter';
+import { MODELS } from './models';
+
+const FAILOVER_CHAIN = [
+  MODELS.SMART,       // Try Sonnet first
+  MODELS.FAST,        // Fall back to Mistral
+  MODELS.BUDGET,      // Last resort: Llama
+];
+
+export async function chatWithFailover(
+  messages: Array<{ role: string; content: string }>,
+  options: {
+    preferredModel?: string;
+    maxTokens?: number;
+    temperature?: number;
+  } = {}
+) {
+  const chain = options.preferredModel
+    ? [options.preferredModel, ...FAILOVER_CHAIN.filter(m => m !== options.preferredModel)]
+    : FAILOVER_CHAIN;
+
+  let lastError: Error | null = null;
+
+  for (const model of chain) {
+    try {
+      const response = await openrouter.chat.completions.create({
+        model,
+        messages,
+        max_tokens: options.maxTokens ?? 4096,
+        temperature: options.temperature ?? 0.7,
+      });
+
+      return {
+        content: response.choices[0].message.content,
+        model,
+        usage: response.usage,
+        failedOver: model !== chain[0],
+      };
+    } catch (error) {
+      lastError = error as Error;
+      const status = (error as { status?: number }).status;
+
+      // Only retry on provider errors, not client errors
+      if (status && status >= 400 && status < 500 && status !== 429) {
+        throw error; // Client error — don't retry
+      }
+
+      console.warn(`Model ${model} failed, trying next:`, (error as Error).message);
+    }
+  }
+
+  throw new Error(`All models failed. Last error: ${lastError?.message}`);
+}
+```
+
+## 6. Error Handling
+
+### Retry with Exponential Backoff
+
+```typescript
+// lib/ai/retry.ts
+
+interface RetryOptions {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const { maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 30000 } = options;
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      const status = (error as { status?: number }).status;
+
+      // Don't retry on non-retryable errors
+      if (status && status >= 400 && status < 500 && status !== 429) {
+        throw error;
+      }
+
+      if (attempt < maxRetries) {
+        const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+        const jitter = delay * (0.5 + Math.random() * 0.5);
+        await new Promise(resolve => setTimeout(resolve, jitter));
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+// Usage:
+// const response = await withRetry(() => openrouter.chat.completions.create({...}));
+```
+
+### OpenRouter-Specific Error Handling
+
+```typescript
+// lib/ai/errors.ts
+
+export class AIError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public status?: number,
+    public model?: string,
+  ) {
+    super(message);
+    this.name = 'AIError';
+  }
+}
+
+export function handleOpenRouterError(error: unknown): AIError {
+  const err = error as {
+    status?: number;
+    error?: { message?: string; code?: string; type?: string };
+    message?: string;
+  };
+
+  const status = err.status;
+  const message = err.error?.message || err.message || 'Unknown error';
+  const code = err.error?.code || err.error?.type || 'unknown';
+
+  switch (status) {
+    case 400:
+      return new AIError(`Bad request: ${message}`, 'bad_request', status);
+    case 401:
+      return new AIError('Invalid OpenRouter API key', 'auth_error', status);
+    case 402:
+      return new AIError('OpenRouter credit balance exhausted', 'insufficient_credits', status);
+    case 429:
+      return new AIError('Rate limited — slow down or upgrade plan', 'rate_limited', status);
+    case 502:
+    case 503:
+      return new AIError(`Model provider unavailable: ${message}`, 'provider_down', status);
+    default:
+      return new AIError(message, code, status);
+  }
+}
+```
+
+### Graceful Degradation in API Route
+
+```typescript
+// app/api/chat/route.ts (production-grade)
+import { streamText } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { selectModel } from '@/lib/ai/router';
+import { handleOpenRouterError } from '@/lib/ai/errors';
+import { z } from 'zod';
+
+const openrouter = createOpenAI({
+  baseURL: 'https://openrouter.ai/api/v1',
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  headers: {
+    'HTTP-Referer': process.env.NEXT_PUBLIC_SITE_URL || 'https://yoursite.com',
+    'X-Title': process.env.NEXT_PUBLIC_APP_NAME || 'YourApp',
+  },
+});
+
+const RequestSchema = z.object({
+  messages: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string().max(100_000),
+  })).min(1).max(100),
+  model: z.string().optional(),
+});
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const parsed = RequestSchema.safeParse(body);
+
+    if (!parsed.success) {
+      return Response.json({ error: parsed.error.flatten() }, { status: 400 });
+    }
+
+    const { messages } = parsed.data;
+
+    // Smart model selection
+    const lastMessage = messages[messages.length - 1];
+    const model = parsed.data.model || selectModel({
+      messageLength: lastMessage.content.length,
+      hasImages: false,
+      conversationTurns: messages.length,
+      taskType: 'chat',
+    });
+
+    const result = streamText({
+      model: openrouter(model),
+      system: 'You are a helpful assistant. Be concise and accurate.',
+      messages,
+      maxTokens: 4096,
+    });
+
+    return result.toDataStreamResponse();
+  } catch (error) {
+    const aiError = handleOpenRouterError(error);
+
+    // Log for monitoring
+    console.error(`[AI Error] ${aiError.code}:`, aiError.message);
+
+    return Response.json(
+      { error: aiError.message, code: aiError.code },
+      { status: aiError.status || 500 }
+    );
+  }
+}
+```
+
+## 7. Security Checklist
+
+- **API key server-side only** — `OPENROUTER_API_KEY` in `.env.local`, never `NEXT_PUBLIC_`
+- **Rate limiting** — Apply rate limits on `/api/chat` (use `@upstash/ratelimit` or similar)
+- **Input validation** — Zod schema on all request bodies
+- **Input sanitization** — Strip or escape user input before sending to LLM
+- **Output validation** — Never render LLM output with `dangerouslySetInnerHTML`
+- **maxTokens always set** — Prevent runaway costs from unbounded responses
+- **Message count cap** — Limit conversation length (e.g., max 100 messages)
+- **Content length cap** — Reject messages over a sane limit (e.g., 100K chars)
+- **No service_role in client** — All Supabase mutations through server-side client
+
+### Rate Limiting Example
+
+```typescript
+// lib/rate-limit.ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(20, '1 m'), // 20 requests per minute
+  analytics: true,
+});
+
+export async function checkRateLimit(identifier: string) {
+  const { success, limit, remaining, reset } = await ratelimit.limit(identifier);
+  return { success, limit, remaining, reset };
+}
+
+// In API route:
+// const ip = req.headers.get('x-forwarded-for') || 'anonymous';
+// const { success } = await checkRateLimit(ip);
+// if (!success) return Response.json({ error: 'Rate limited' }, { status: 429 });
+```
+
+## 8. Conversation Storage (Supabase)
+
+### Schema
+
+```sql
+-- Conversations table
+CREATE TABLE conversations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  title TEXT,
+  model TEXT NOT NULL DEFAULT 'anthropic/claude-sonnet-4-20250514',
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Messages table
+CREATE TABLE messages (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system', 'tool')),
+  content TEXT NOT NULL,
+  model TEXT,
+  prompt_tokens INT,
+  completion_tokens INT,
+  cost_cents NUMERIC(10, 6),
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- RLS
+ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE messages ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users read own conversations" ON conversations
+  FOR ALL USING (user_id = auth.uid());
+
+CREATE POLICY "Users read own messages" ON messages
+  FOR ALL USING (
+    EXISTS (
+      SELECT 1 FROM conversations c
+      WHERE c.id = messages.conversation_id
+      AND c.user_id = auth.uid()
+    )
+  );
+
+-- Indexes
+CREATE INDEX idx_conversations_user ON conversations(user_id);
+CREATE INDEX idx_messages_conversation ON messages(conversation_id);
+CREATE INDEX idx_messages_created ON messages(created_at);
+```
+
+### Save Conversation Helper
+
+```typescript
+// lib/ai/storage.ts
+import { createClient } from '@/lib/supabase/server';
+
+export async function saveMessage(
+  conversationId: string,
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  usage?: { promptTokens?: number; completionTokens?: number; costCents?: number; model?: string }
+) {
+  const supabase = await createClient();
+
+  const { error } = await supabase.from('messages').insert({
+    conversation_id: conversationId,
+    role,
+    content,
+    model: usage?.model,
+    prompt_tokens: usage?.promptTokens,
+    completion_tokens: usage?.completionTokens,
+    cost_cents: usage?.costCents,
+  });
+
+  if (error) throw error;
+
+  // Update conversation timestamp
+  await supabase
+    .from('conversations')
+    .update({ updated_at: new Date().toISOString() })
+    .eq('id', conversationId);
+}
+
+export async function loadConversation(conversationId: string) {
+  const supabase = await createClient();
+
+  const { data, error } = await supabase
+    .from('messages')
+    .select('role, content')
+    .eq('conversation_id', conversationId)
+    .order('created_at', { ascending: true });
+
+  if (error) throw error;
+  return data;
+}
+
+export async function createConversation(userId: string, title?: string) {
+  const supabase = await createClient();
+
+  const { data, error } = await supabase
+    .from('conversations')
+    .insert({ user_id: userId, title: title || 'New Chat' })
+    .select('id')
+    .single();
+
+  if (error) throw error;
+  return data.id;
+}
+```
+
+## Quick Start Checklist
+
+When user asks to build an AI agent or chatbot, follow this order:
+
+1. **Dependencies**: `npm install ai @ai-sdk/openai openai zod`
+2. **Environment**: Add `OPENROUTER_API_KEY` to `.env.local`
+3. **OpenRouter client**: Create `lib/openrouter.ts`
+4. **Model constants**: Create `lib/ai/models.ts`
+5. **API route**: Create `app/api/chat/route.ts` with streaming
+6. **Client UI**: Create chat page with `useChat` hook
+7. **Tools** (if needed): Define in `lib/ai/tools.ts`, wire into route
+8. **Storage** (if needed): Run Supabase migration, create `lib/ai/storage.ts`
+9. **Cost routing** (if needed): Create `lib/ai/router.ts`
+10. **Error handling**: Add retry, failover, graceful degradation
+11. **Security**: Rate limiting, Zod validation, maxTokens cap
+
+## Key Decisions to Ask User
+
+- **Model**: Which model for primary use? (Default: Sonnet for balance)
+- **Streaming**: Stream responses or wait for full response? (Default: stream)
+- **Tools**: Does the agent need to call external APIs or query databases?
+- **Persistence**: Store conversations in Supabase? (Recommended for production)
+- **Auth**: Require login to chat? (Recommended — use Supabase auth)
+- **Cost controls**: Budget cap per user? Smart model routing?
+- **Rate limiting**: How many requests per minute? (Default: 20/min)
+
+## Environment Variables Needed
+
+```env
+# Required
+OPENROUTER_API_KEY=sk-or-v1-...
+
+# Optional — for conversation storage
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+
+# Optional — for rate limiting
+UPSTASH_REDIS_REST_URL=https://...
+UPSTASH_REDIS_REST_TOKEN=...
+
+# App metadata (sent to OpenRouter for tracking)
+NEXT_PUBLIC_SITE_URL=https://yoursite.com
+NEXT_PUBLIC_APP_NAME=YourApp
+```
+
+## Integration with Other Skills
+
+- **rag** — Add RAG retrieval as a tool for grounded responses
+- **voice-agent** — Use OpenRouter for voice agent LLM backend
+- **supabase** — Conversation storage, user auth, RLS
+- **frontend-master** — Build polished chat UI
+
+## Trigger Phrases
+
+- "build AI agent" / "build chatbot" / "chat feature"
+- "openrouter" / "LLM integration" / "AI streaming"
+- "model selection" / "which AI model"
+- "chat endpoint" / "chat API"
+- "function calling" / "tool calling"
+- "AI cost" / "model routing" / "failover"