SA Post Generator

Process

Step 1 — Load Brand Profile

import { db } from '@/lib/db';
import { brandProfiles } from '@/drizzle/schema';

const profile = await db.query.brandProfiles.findFirst({
  where: (t, { eq, and }) => and(eq(t.userId, userId), eq(t.platform, platform)),
});
// If no profile exists, use neutral defaults and suggest running brand-scraper skill

Step 2 — Build the SA Cultural Context Layer

Always inject the following into the Gemini prompt:

const saContextLayer = `
You are writing for a South African audience.
- Timezone: SAST (UTC+2)
- Currency: ZAR
- Use culturally authentic language: ${language} 
- Weave in SA expressions naturally (e.g. "Howzit", "Sharp sharp", "Lekker", "Eish", "Jozi vibes", "Durban heat")
- Reference SA cities where relevant: Johannesburg/Jozi, Cape Town, Durban, Pretoria/Tshwane, Port Elizabeth/Gqeberha
- Use SA-relevant hashtags: #Mzansi #LocalIsLekker #MzansiMagic #Joburg #CapeTown #SAProud
- For Zulu (zu): use Ubuntu philosophy undertones
- For Afrikaans (af): warm, community-focused tone
- Cultural calendar awareness: Heritage Day (24 Sep), Youth Day (16 Jun), Freedom Day (27 Apr), Braai Day
`;

Step 3 — Compose Gemini Prompt

import { GoogleGenerativeAI } from '@google/genai';

const ai = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = ai.getGenerativeModel({ model: 'gemini-pro' });

const prompt = `
${saContextLayer}

Brand voice: ${JSON.stringify(profile?.toneFingerprint ?? { casual: 0.5, inspirational: 0.5 })}
Top brand vocabulary: ${profile?.topVocabulary?.slice(0, 15).join(', ') ?? 'none'}
Brand hashtags: ${Object.keys(profile?.hashtagFrequency ?? {}).slice(0, 8).join(' ')}

Task: Write a ${platform} post about "${topic}" in ${language}.
Tone: ${tone} (formal | casual | inspirational | humorous)
Max length: ${characterLimit} characters — NEVER exceed this.
Generate ${variationCount} distinct variations. Return as JSON array of strings.
`;

Step 4 — Post-Process Output

For each generated variation:

1. Strip any markdown formatting Gemini adds
2. Enforce character limit (truncate at word boundary if over)
3. Validate language code matches requested language
4. Score SA cultural authenticity (0–1): presence of SA hashtags, expressions, or city refs
5. Rank variations: engagementScore = saAuthenticityScore * 0.4 + brandAlignmentScore * 0.6

Step 5 — Return & Persist

Return top-ranked variations to the caller. Persist generation metadata for the feedback loop:

await db.insert(postGenerations).values({
  userId,
  platform,
  language,
  tone,
  topic,
  generatedCount: variationCount,
  topVariationHash: hashString(topVariation),
  saAuthenticityScore,
  brandAlignmentScore,
  createdAt: new Date(),
});

Step 6 — Feedback Loop (async, post-publish)

When a post is published and performance data arrives (via lib/inngest/functions/learn-ai-patterns.ts):

// Update brand profile weights based on high-performing posts
if (post.engagementRate > profile.avgEngagementRate * 1.5) {
  // Boost: tone weight of this post's tone, any SA hashtags used, vocabulary matches
  await boostBrandProfileFeatures(userId, platform, post);
}

Output Format

interface GenerationResult {
  variations: {
    text: string;
    characterCount: number;
    saAuthenticityScore: number;  // 0-1
    brandAlignmentScore: number;  // 0-1
    suggestedHashtags: string[];
    suggestedImagePrompt?: string;
  }[];
  topVariationIndex: number;
  language: string;
  platform: string;
  generationId: string;
}

SA Language Quick Reference

Examples

Example 1 — Twitter in Zulu

Input: topic="coffee shop opening", platform="twitter", language="zu", tone="casual"
Output: "Sawubona ✨ Siyavula ngokuvula i-coffee shop yethu entsha eJozi! ☕
Woza uzizwe ubuntu bethu ngosuku lokuqala 🙌 #Mzansi #LocalIsLekker #JoziVibes"
(226 chars — within limit)

Example 2 — LinkedIn in English with Afrikaans flavour

Input: topic="product launch", platform="linkedin", language="en", tone="professional"
Output: "Baie excited to share that after 18 months of building...
[professional post with SA context woven in naturally]
#LocalIsLekker #MzansiBusiness #ProudlySouthAfrican"

Troubleshooting

1. Gemini rate limit — Implement exponential backoff; surface { error: 'AI_RATE_LIMIT', retryAfterMs } to caller
2. No brand profile — Generate with neutral defaults; append inline suggestion to run brand-scraper
3. Character limit exceeded after generation — Truncate at last complete sentence before limit; never cut mid-word