# AI Wrapper Product - Detailed Guide

> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.

## Capabilities

- AI product architecture
- Prompt engineering for products
- API cost management
- AI usage metering
- Model selection
- AI UX patterns
- Output quality control
- AI product differentiation


These are illustrative architecture fragments with unbundled `db`, cache, parser, sleep and business helpers. Historical model names/prices/latencies below are not current recommendations; verify supported model IDs, dated provider pricing and measured workload latency. Keep API credentials server-side, enforce user/tenant authorization and approve data/provider/budget before calls. Treat model output as untrusted data; structured shape does not prove factual correctness or authorize sending emails/actions.

### AI Product Architecture

Building products around AI APIs

**When to use**: When designing an AI-powered product


## AI Product Architecture

### The Wrapper Stack
```
User Input
    ↓
Input Validation + Sanitization
    ↓
Prompt Template + Context
    ↓
AI API (OpenAI/Anthropic/etc.)
    ↓
Output Parsing + Validation
    ↓
User-Friendly Response
```

### Basic Implementation
```javascript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

async function generateContent(userInput, context) {
  // 1. Validate input
  if (typeof userInput !== "string" || !userInput.trim() || userInput.length > 5000) {
    throw new Error('Invalid input');
  }

  // 2. Build prompt
  const systemPrompt = `You are a ${context.role}.
    Always respond in ${context.format}.
    Tone: ${context.tone}`;

  // 3. Call API
  const response = await anthropic.messages.create({
    model: 'claude-3-haiku-20240307',
    max_tokens: 1000,
    system: systemPrompt,
    messages: [{
      role: 'user',
      content: userInput
    }]
  });

  // 4. Parse and validate output
  if (response.stop_reason !== "end_turn") throw new Error("Incomplete/refused output");
  const output = response.content.filter(p => p.type === "text").map(p => p.text).join("\n");
  return parseAIOutput(output);
}
```

### Model Selection
| Model | Cost | Speed | Quality | Use Case |
|-------|------|-------|---------|----------|
| GPT-4o | $$$ | Fast | Best | Complex tasks |
| GPT-4o-mini | $ | Fastest | Good | Most tasks |
| Claude 3.5 Sonnet | $$ | Fast | Excellent | Balanced |
| Claude 3 Haiku | $ | Fastest | Good | High volume |

### Prompt Engineering for Products

Production-grade prompt design

**When to use**: When building AI product prompts


## Prompt Engineering for Products

### Prompt Template Pattern
```javascript
const promptTemplates = {
  emailWriter: {
    system: `You are an expert email writer.
      Write professional, concise emails.
      Match the requested tone.
      Never include placeholder text.`,
    user: (input) => `Write an email:
      Purpose: ${input.purpose}
      Recipient: ${input.recipient}
      Tone: ${input.tone}
      Key points: ${input.points.join(', ')}
      Length: ${input.length} sentences`,
  },
};
```

### Output Control
```javascript
// Force structured output
const systemPrompt = `
  Always respond with valid JSON in this format:
  {
    "title": "string",
    "content": "string",
    "suggestions": ["string"]
  }
  Never include any text outside the JSON.
`;

// Parse with fallback
function parseAIOutput(text) {
  const value = JSON.parse(text); // Reject surrounding text; no greedy-brace repair.
  if (!value || typeof value.title !== 'string' || typeof value.content !== 'string' ||
      !Array.isArray(value.suggestions) || !value.suggestions.every(x => typeof x === 'string')) {
    throw new Error('Invalid AI output schema');
  }
  return value;
}
```

### Quality Control
| Technique | Purpose |
|-----------|---------|
| Examples in prompt | Guide output style |
| Output format spec | Consistent structure |
| Validation | Catch malformed responses |
| Retry logic | Handle failures |
| Fallback models | Reliability |

### Cost Management

Controlling AI API costs

**When to use**: When building profitable AI products


## AI Cost Management

### Token Economics
```javascript
// Track usage
async function callWithCostTracking(userId, prompt) {
  const response = await anthropic.messages.create({...});

  // Log usage
  await db.usage.create({
    userId,
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
    cost: calculateCost(response.usage),
    model: 'claude-3-haiku',
  });

  return response;
}

function calculateCost(usage) {
  const rates = {
    'claude-3-haiku': { input: 0.25, output: 1.25 }, // per 1M tokens
  };
  const rate = rates['claude-3-haiku'];
  return (usage.input_tokens * rate.input +
          usage.output_tokens * rate.output) / 1_000_000;
}
```

### Cost Reduction Strategies
| Strategy | Savings |
|----------|---------|
| Use cheaper models | 10-50x |
| Limit output tokens | Variable |
| Cache common queries | High |
| Batch similar requests | Medium |
| Truncate input | Variable |

### Usage Limits
```javascript
async function checkUsageLimits(userId) {
  const usage = await db.usage.sum({
    where: {
      userId,
      createdAt: { gte: startOfMonth() }
    }
  });

  const limits = await getUserLimits(userId);
  if (usage.cost >= limits.monthlyCost) {
    throw new Error('Monthly limit reached');
  }
  return true;
}
```

### AI Product Differentiation

Standing out from other AI wrappers

**When to use**: When planning AI product strategy


## AI Product Differentiation

### What Makes AI Products Defensible
| Moat | Example |
|------|---------|
| Workflow integration | Email inside Gmail |
| Domain expertise | Legal AI with law training |
| Data/context | Company-specific knowledge |
| UX excellence | Perfectly designed for task |
| Distribution | Built-in audience |

### Differentiation Strategies
```
1. Vertical Focus
   Generic: "AI writing assistant"
   Specific: "AI for Amazon product descriptions"

2. Workflow Integration
   Standalone: Web app
   Integrated: Chrome extension, Slack bot

3. Domain Training
   Generic: Uses raw GPT
   Specialized: Fine-tuned or RAG-enhanced

4. Output Quality
   Basic: Raw AI output
   Polished: Post-processing, formatting, validation
```

### Avoid "Thin Wrappers"
| Thin Wrapper | Real Product |
|--------------|--------------|
| ChatGPT with custom prompt | Domain-specific workflow tool |
| API passthrough | Processed, validated outputs |
| Single feature | Complete solution |
| No unique value | Solves specific pain point |


## Sharp Edges

### AI API costs spiral out of control

Severity: HIGH

Situation: Monthly AI bill is higher than revenue

Symptoms:
- Surprise API bills
- Costs > revenue
- Rapid usage spikes
- No visibility into costs

Why this breaks:
No usage tracking.
No user limits.
Using expensive models.
Abuse or bugs.

Recommended fix:


## Controlling AI Costs

Usage examples below are check-only sketches and race under concurrent requests. Reserve worst-case call cost atomically per user/tenant before submitting, bound concurrency/output, then reconcile actual token/cache/tool charges. Persist provider operation IDs and handle crashes/uncertain outcomes so retries do not duplicate billable work. Provider dashboard budgets/alerts are not necessarily a hard spend cap; verify actual enforcement. Do not cache across tenants or authorization scopes: include model/prompt/schema versions and permitted context in keys.

### Set Hard Limits
```javascript
// Per-user limits
const LIMITS = {
  free: { dailyCalls: 10, monthlyTokens: 50000 },
  pro: { dailyCalls: 100, monthlyTokens: 500000 },
};

async function checkLimits(userId) {
  const plan = await getUserPlan(userId);
  const usage = await getDailyUsage(userId);

  if (usage.calls >= LIMITS[plan].dailyCalls) {
    throw new Error('Daily limit reached');
  }
}
```

### Provider-Level Limits
```
OpenAI: Set usage limits in dashboard
Anthropic: Set spend limits
Add alerts at 50%, 80%, 100%
```

### Cost Monitoring
```javascript
// Alert on anomalies
async function checkCostAnomaly() {
  const todayCost = await getTodayCost();
  const avgCost = await getAverageDailyCost(30);

  if (todayCost > avgCost * 3) {
    await alertAdmin('Cost anomaly detected');
  }
}
```

### Emergency Shutoff
```javascript
// Kill switch
const MAX_DAILY_SPEND = 100; // $100

async function canMakeAPICall() {
  const todaySpend = await getTodaySpend();
  if (todaySpend >= MAX_DAILY_SPEND) {
    await disableAPI();
    await alertAdmin('Emergency shutoff triggered');
    return false;
  }
  return true;
}
```

### App breaks when hitting API rate limits

Severity: HIGH

Situation: API calls fail with 429 errors

Symptoms:
- 429 Too Many Requests errors
- Requests failing in bursts
- Users seeing errors
- Inconsistent behavior

Why this breaks:
No retry logic.
Not queuing requests.
Burst traffic not handled.
No backoff strategy.

Recommended fix:


## Handling Rate Limits

### Retry with Exponential Backoff
```javascript
async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await sleep(delay);
        continue;
      }
      throw err;
    }
  }
}
```

### Request Queue
```javascript
import PQueue from 'p-queue';

// Limit concurrent requests
const queue = new PQueue({
  concurrency: 5,
  interval: 1000,
  intervalCap: 10, // Max 10 per second
});

async function callAPI(prompt) {
  return queue.add(() => anthropic.messages.create({...}));
}
```

### User-Facing Handling
```javascript
try {
  const result = await callWithRetry(generateContent);
  return result;
} catch (err) {
  if (err.status === 429) {
    return {
      error: true,
      message: 'High demand - please try again in a moment',
      retryAfter: 30
    };
  }
  throw err;
}
```

### AI gives wrong or made-up information

Severity: HIGH

Situation: Users complain about incorrect outputs

Symptoms:
- Users report wrong information
- Made-up facts in outputs
- Outdated information
- Trust issues

Why this breaks:
No output validation.
Trusting AI blindly.
No fact-checking.
Wrong use case for AI.

Recommended fix:


## Handling Hallucinations

### Output Validation
```javascript
function validateOutput(output, schema) {
  // Check required fields
  if (!output.title || !output.content) {
    throw new Error('Missing required fields');
  }

  // Check reasonable length
  if (output.content.length < 50 || output.content.length > 5000) {
    throw new Error('Content length out of range');
  }

  // Check for placeholder text
  const placeholders = ['[INSERT', 'PLACEHOLDER', 'YOUR NAME HERE'];
  if (placeholders.some(p => output.content.includes(p))) {
    throw new Error('Output contains placeholders');
  }

  return true;
}
```

### Domain-Specific Validation
```javascript
// For factual content
async function validateFacts(output) {
  // Check dates are reasonable
  const dates = extractDates(output);
  for (const date of dates) {
    if (date > new Date() || date < new Date('1900-01-01')) {
      return { valid: false, reason: 'Suspicious date' };
    }
  }

  // Check numbers are reasonable
  // ...
}
```

### Use Cases to Avoid
| Risky | Safer Alternative |
|-------|-------------------|
| Medical advice | Summarize, not diagnose |
| Legal advice | Draft, not advise |
| Current events | Use with data sources |
| Precise calculations | Validate or use code |

### User Expectations
- Disclaimer for generated content
- "AI-generated" labels
- Edit capability for users
- Feedback mechanism

### AI responses too slow for good UX

Severity: MEDIUM

Situation: Users complain about slow responses

Symptoms:
- Long wait times
- Users abandoning
- Timeout errors
- Poor perceived performance

Why this breaks:
Large prompts.
Expensive models.
No streaming.
No caching.

Recommended fix:


## Improving AI Latency

### Streaming Responses
```javascript
// Stream to user as AI generates
async function* streamResponse(prompt) {
  const stream = await anthropic.messages.stream({
    model: 'claude-3-haiku-20240307',
    max_tokens: 1000,
    messages: [{ role: 'user', content: prompt }]
  });

  for await (const event of stream) {
    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
      yield event.delta.text;
    }
  }
}

// Frontend
const response = await fetch('/api/generate', { method: 'POST' });
if (!response.ok || !response.body) throw new Error("Generation failed");
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  appendToOutput(decoder.decode(value, { stream: true }));
}
```

Flush `decoder.decode()` after stream end and render generated text safely (not unsanitized innerHTML). Cancel upstream generation on authorized client cancellation where supported.

### Caching
```javascript
async function generateWithCache(prompt) {
  const cacheKey = hashPrompt(prompt);
  const cached = await cache.get(cacheKey);
  if (cached) return cached;

  const result = await generateContent(prompt);
  await cache.set(cacheKey, result, { ttl: 3600 });
  return result;
}
```

### Use Faster Models
| Model | Typical Latency |
|-------|-----------------|
| GPT-4 | 5-15s |
| GPT-4o-mini | 1-3s |
| Claude 3 Haiku | 1-3s |
| Claude 3.5 Sonnet | 2-5s |


## Validation Checks

### AI API Key Exposed

Severity: HIGH

Message: AI API key may be exposed - security risk!

Fix action: Move API calls to backend, use environment variables

### No AI Usage Tracking

Severity: HIGH

Message: Not tracking AI usage - cost control issue.

Fix action: Log tokens and costs for every API call

### No AI Error Handling

Severity: HIGH

Message: AI errors not handled gracefully.

Fix action: Add try/catch, retry logic, and user-friendly error messages

### No AI Output Validation

Severity: MEDIUM

Message: Not validating AI outputs.

Fix action: Add output parsing, validation, and error handling

### No Response Streaming

Severity: LOW

Message: Not using streaming - could improve UX.

Fix action: Implement streaming for better perceived performance


## Collaboration

### Delegation Triggers

- prompt engineering|advanced LLM|fine-tuning -> llm-architect (Advanced AI patterns)
- SaaS|pricing|launch|business -> micro-saas-launcher (AI product business)
- frontend|UI|react -> frontend (AI product interface)
- backend|API|database -> backend (AI product backend)
- browser extension -> browser-extension-builder (AI browser extension)
- telegram bot -> telegram-bot-builder (AI telegram bot)

### AI Writing Tool

Skills: ai-wrapper-product, frontend, micro-saas-launcher

Workflow:

```
1. Define specific writing use case
2. Design prompt templates
3. Build UI with streaming
4. Add usage tracking and limits
5. Implement payments
6. Launch and iterate
```

### AI Browser Extension

Skills: ai-wrapper-product, browser-extension-builder

Workflow:

```
1. Define AI-powered feature
2. Build extension structure
3. Integrate AI API via backend
4. Add usage limits
5. Publish to Chrome Store
```

### AI Telegram Bot

Skills: ai-wrapper-product, telegram-bot-builder

Workflow:

```
1. Define bot personality/purpose
2. Build Telegram bot
3. Integrate AI for responses
4. Add monetization
5. Launch and grow
```


## Related Skills

Works well with: `llm-architect`, `micro-saas-launcher`, `frontend`, `backend`