Content Pipeline

Content Pipeline — AI Content Generation Guide

Visual generation (binding): all images/video route through the grounded pipeline — see .claude/rules/real-images-only.md + the grounded-visuals skill. Direct provider calls fail CI. This guide covers TEXT content only — see "Image & video generation" below before reaching for an image/video path.

Purpose

SYNTHEX generates content through a multi-layer pipeline: model registry selects the right LLM, provider abstraction handles API differences, BYOK key injection uses the user's own API key when available, and content scoring evaluates quality without any AI calls.

This skill documents the full pipeline flow and the key decisions at each stage — for text content. Image and video generation are a separate, mandated path; see "Image & video generation" below.

Pipeline Flow

User Request
  │
  ▼
ContentRequest (type, platform, tone, persona)
  │
  ▼
API Credential Injector ─── Does user have a BYOK key?
  │                           YES → Decrypt and use user's key
  │                           NO  → Use platform OPENROUTER_API_KEY
  ▼
Provider Abstraction (getAIProvider)
  │
  ├─ OpenRouter Provider (primary, supports 100+ models)
  ├─ Anthropic Provider (direct Claude access)
  ├─ Google Provider (Gemini models)
  └─ OpenRouter Provider with OpenAI keys (passthrough)
  │
  ▼
Model Registry → Select model by provider + tier
  │
  ▼
Content Generator → Build prompt with persona, platform rules
  │
  ▼
Generated Content
  │
  ▼
Content Scorer → Score across 5 dimensions (no AI call)
  │
  ▼
Content Repurposer → Adapt for multiple platforms

Image & video generation — separate mandated path (REAL IMAGES ONLY)

Everything above is the text pipeline (getAIProvider()). It does not cover images or video. ALL image/video generation goes ONLY through generateImage()/generateBatch() in lib/services/ai/image-generation.ts (video via lib/services/ai/video/generation-service.ts), grounded-by-default on the owned reference library (public/reference-library/manifest.json, 143+ subjects; private Supabase bucket reference-library-private via POST /api/admin/private-refs). Industry is auto-detected from the prompt; no owned references ⇒ blocked: true ("No owned references for this subject — add real photos to the reference library first"); useReferences: false is the audited UNGROUNDED escape hatch. The carpet-style-v1 LoRA (trigger ccwcarpet, lib/services/ai/image/trained-loras.json) auto-applies for carpet-cleaning. The static guard test tests/unit/ai/no-direct-image-apis.test.ts fails CI on any direct provider call. MCP studio tools generate_image/ generate_video inherit these defaults. The dashboard runs 3-variant batches with tap-to-rank (image_generations lineage, groundedShare insight). See .claude/rules/real-images-only.md + .claude/skills/grounded-visuals/.

Model Registry

File: lib/ai/model-registry.ts Purpose: Single source of truth for which models SYNTHEX uses system-wide

Types:

• AIProvider: 'openai' | 'anthropic' | 'google' | 'openrouter'
• ModelTier: 'latest' | 'production' | 'legacy'
• ModelConfig: Full model specification (id, capabilities, cost, context window)

Key functions:

• getAllLatestModels() — Returns the latest model for each provider
• Models not in the registry are rejected by the system

Admin refresh: POST /api/system/models (owner-only) calls modelManager.forceUpdate()

Model Manager: lib/ai/model-manager.ts — Handles health monitoring, auto-failover, and periodic registry refresh.

Provider Abstraction

Files:

• lib/ai/providers/index.ts — Factory function getAIProvider()
• lib/ai/providers/base-provider.ts — Abstract base class
• lib/ai/providers/openrouter-provider.ts — OpenRouter implementation
• lib/ai/providers/anthropic-provider.ts — Anthropic (Claude) direct
• lib/ai/providers/google-provider.ts — Google (Gemini) direct

Usage:

import { getAIProvider } from '@/lib/ai/providers';

const ai = getAIProvider({ apiKey: userKey || undefined });
const response = await ai.complete({
  model: 'gpt-4-turbo',
  messages: [{ role: 'user', content: prompt }],
  temperature: 0.7,
});

Key pattern: All providers implement the same interface. The factory selects the right provider based on the model ID or explicit provider parameter.

BYOK Key Injection

File: lib/ai/api-credential-injector.ts Purpose: Bridges user-stored API credentials into AI provider calls

Flow:

1. Look up user's API credential in DB (prisma.aPICredential.findFirst)
2. Filter: isActive: true, revokedAt: null, most recent first
3. Decrypt with decryptApiKey() from lib/encryption/api-key-encryption.ts
4. Pass decrypted key to getAIProvider({ apiKey }) — overrides platform key

Provider mapping:

openrouter → openrouter
openai     → openrouter (OpenAI keys work through OpenRouter)
anthropic  → anthropic
google     → google

Security:

• Keys stored encrypted at rest (AES-256-GCM)
• Decrypted only at point of use, never logged
• revokedAt field prevents use of compromised keys

Legacy OpenRouter Client

File: lib/ai/openrouter-client.ts Purpose: Direct OpenRouter API calls (legacy — prefer provider abstraction)

Environment variables:

• OPENROUTER_API_KEY — Platform-level API key
• OPENROUTER_SITE_NAME — App name header
• OPENROUTER_SITE_URL — App URL header

When to use: Only for legacy code paths. New code should use getAIProvider().

Content Generator

File: lib/ai/content-generator.ts Purpose: Multi-model content creation with persona-based voice consistency

ContentRequest fields:

• type: post, caption, thread, story, reel, article
• platform: twitter, instagram, linkedin, tiktok, facebook, youtube
• tone: professional, casual, humorous, inspirational, educational
• personaId: Optional trained persona for voice/style consistency
• keywords, targetAudience, length, includeEmojis, includeHashtags, includeCTA

Persona integration: When personaId is provided, the generator loads the persona's tone, style, vocabulary, and emotion settings from the database and injects them into the system prompt.

Content Scorer

File: lib/ai/content-scorer.ts Purpose: Real-time content quality scoring with zero AI calls

Five dimensions (0-100 each):

Overall score: Weighted average of all five dimensions.

Key design choice: Pure functions with no AI calls. This enables real-time scoring in the UI without latency or cost.

Content Repurposer

File: lib/ai/content-repurposer.ts Purpose: Adapts a single piece of content for multiple platforms

Takes generated content and transforms it to match each platform's format, character limits, and audience expectations.

Common Mistakes

Environment Variables

File Index

Reference skill: This is a read-only architecture guide — it documents existing systems and does not generate creative or code output. No capability uplift block is needed.

Foundation & Gate Wiring (SYN-1050)

Adopted from the senior-skill standard so every artefact this skill produces is checked against the locked foundation before it lands.

Reads at every invocation (never cached — re-read each run):

• .claude/memory/ceo-foundation.md — voice tag (Q2.5.5), universal + brand-specific taboos, verification gates for any quantitative claim.
• .claude/memory/verification-gates.md — gate state for any claim referenced.

Output gate: every client-facing artefact this skill produces routes through brand-voice-enforce before the CEO batched-review queue. A REJECT blocks the artefact until the quoted offending string is fixed.

Evidence standard: every quantitative or factual claim carries exactly one tag — [VERIFIED] / [INFERENCE] / [UNCONFIRMED]. Untagged = defect (.claude/rules/fabel-evidence-standard.md). Never state a projected result as fact.

Spec: see spec.md in this skill directory.