Turns a job title or person description into three wildly enthusiastic, slightly unhinged compliments.
- Exactly three distinct compliments at once, with atomic success and one same-bucket recovery attempt for a failed slot
- Separate required workplace-function and optional person-details inputs
- Each card has independent conversation history
- "Make it more dramatic" escalates only the selected card, using its own prior versions, and caps at drama level 6 with a one-shot celebration
- Copy to clipboard with per-card confirmation and fallback copy support
- Intentional loading, friendly errors, and mobile-first layout
- Premium workspace with saved decks, per-card version history, tweak notes, and light taste signals
- Clean share links at
/deck/<short-id>with a public, readable deck page - Per-card native sharing, X/LinkedIn/WhatsApp copy formats, and downloadable 1200x1200 PNG cards
- User-triggered read aloud with the device's built-in speech synthesizer and an immediate stop control
- Crawlable compliment guide, metadata, Open Graph image, JSON-LD,
robots.txt, and sitemap - Company Compliment Guidelines v2.1 enforced across generation, retry, tweak, and escalation
- Per-version 8/8 rule proof with code, evidence, heuristic, and model check sources; the badge headline honestly splits code-verified from AI-audited checks, with a settings toggle for the wording
- Per-role Gemini model selection (writer, backup, judge) on the private admin page, from a predefined allowlist; the server honors overrides only from an authenticated admin session and everyone else gets the environment defaults
- Independent semantic validator for appearance, metaphor quality, public figures, workplace safety, and escalation quality
- Deck-wide duplicate, opening, metaphor, statistic, persona-fit, imagery, and humor checks with targeted card regeneration
- Private code-protected diagnostics at
/admin, with a 30-day signed session, error-first request history, complete redacted server timelines, model outputs, rule failures, provider errors, and automatic-repair outcomes
Next.js App Router, TypeScript, Tailwind CSS, server API routes, Vercel AI SDK, Gemini via @ai-sdk/google, Zod, Upstash Redis for durable production shares and diagnostics logs, Playwright, axe-core, and a signed HMAC cookie rate limit.
Gemini 3.1 Flash-Lite by default (with an automatic backup model and a temperature-0 validator pass), for three reasons: it is fast and free-tier friendly, so generating three compliments plus a compliance audit per request stays affordable; it supports structured output natively, so "exactly one compliment with exact rule evidence" is enforced by schema instead of hoped for; and the same family serves as an independent validator model, keeping the show-your-work audit on one provider.
The private admin page can switch each model role (writer, backup, judge) at request time from a predefined list in lib/models.ts, from Flash-Lite up to Pro. The admin's browser stores the choice locally and sends it with each request; the server honors an override only when the request carries a valid admin session, accepts only allowlisted model ids, and otherwise falls back to the GEMINI_MODEL_* environment defaults. A full requirement-to-code map lives in COMPLIANCE.md.
Each compliment is generated by a distinct comedic persona in its own model call. The cast has eight personas in three style buckets: grand (Distinguished Awards Committee, Startup Hype Deck, Overdramatic Theater Critic), mythic (Epic Bard, Ancient Oracle, Nature Documentary Narrator), and chaotic (Overcaffeinated Hype Friend, Sports Commentator). Every run picks one persona per bucket, so two cards can never share a voice. Each persona owns an explicit imagery lane, a list of lanes it must avoid, and one few-shot example written for a person who never appears in real input. The three primary pipelines run concurrently. If one slot fails, it gets one same-bucket fallback; success is atomic, so the API never labels a one- or two-card result as a finished deck.
After per-card compliance, deterministic checks reject duplicate wording, openings, metaphors, and statistics. One consolidated temperature-zero deck audit then compares all three candidates for persona fit, imagery-domain separation, and humor variety. Only an offending card is regenerated, with the accepted cards and audit feedback supplied as material to avoid. This adds semantic diversity without multiplying the audit into three redundant pairwise calls. If this optional deck judge is unavailable after model/key fallback, the server may accept only a deck that still clears the deterministic diversity gate; the eight company rules never use that availability fallback.
Gemini returns a typed compliment plus exact role, metaphor, and fictional-statistic evidence. The server deterministically verifies the 40-word limit, banned word, evidence quotes, function grounding, statistic pattern, and conservative safety patterns. A separate validator-model call independently evaluates indirect appearance references, metaphor absurdity, public-figure comparisons, workplace safety, and whether escalation is meaningfully stronger. Generation gets one targeted repair; escalation gets up to three total attempts. Only outputs that pass every check reach the UI.
Each card stores the current text, public compliment history, persona id, drama level, compliance proof, loading status, and copy state. Every saved version retains its own proof, so drama navigation, saved decks, and public shares keep the matching text and verification together. Escalation sends only that card's versions back to /api/escalate, and the server replays them to the model as a literal multi-turn conversation: the original request as a user turn, each prior compliment as an assistant turn, and the new escalation instruction as the newest user turn. Level 3 therefore builds on level 2 inside a real conversation instead of a pasted summary, and the tweak feature uses the same structure. The server rebuilds the persona/system prompt from personaId, so hidden instructions never ship to the browser and card histories cannot contaminate one another.
cp .env.example .env.localSet GEMINI_API_KEY and RATELIMIT_SECRET. Optional numbered backups (GEMINI_API_KEY_2 and up) enable automatic key rotation; HYPEFORGE_GEMINI_API_KEY remains as a legacy single-key fallback when no pool key is set. Set NEXT_PUBLIC_SITE_URL to the deployed public origin so canonical URLs, sitemap entries, and social metadata point to the real site. HypeForge has no local/internal text generator fallback; every compliment comes from Gemini. If Gemini quota is exhausted, the app shows a friendly error and logs the real provider details server-side. Keep .env.local out of git.
For private operational history, enable HYPEFORGE_CAPTURE_AI_FAILURES, set independent random values for HYPEFORGE_ADMIN_CODE and HYPEFORGE_ADMIN_SESSION_SECRET, and optionally enable HYPEFORGE_DEBUG_STACKS. Production logs use Upstash Redis when UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set (kept in one capped list read with a single LRANGE); without them, local logs stay under .data/. Person input is stored only as a short SHA-256 fingerprint and word count. API keys, authorization headers, and hidden prompts are redacted or omitted.
Shared decks use a local JSON store by default at .data/hypeforge-shares.json. In production the app stores each share in Upstash Redis under a namespaced hypeforge:share:<slug> key when UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN are set; another host may use HYPEFORGE_SHARE_STORE_PATH on a persistent disk. Shared deck pages are intentionally noindex: they get good link previews without making a recipient's praise searchable.
pnpm install
pnpm devOpen http://localhost:3000. The old /v2 path still works and redirects to the homepage, so previously shared links keep resolving.
pnpm lint
pnpm typecheck
pnpm test
pnpm test:a11y
pnpm test:browsers
pnpm build
pnpm verify:api
pnpm eval:qualityeval:quality runs a 36-role, direct/public corpus through the real endpoint and fails unless every case returns exactly three compliant cards with all three voice buckets and basic lexical separation. Use HYPEFORGE_EVAL_LIMIT=3 for a quick smoke run, HYPEFORGE_EVAL_START=2 HYPEFORGE_EVAL_LIMIT=1 to replay corpus case 3, or HYPEFORGE_EVAL_OUTPUT=.data/quality-eval.json to retain a detailed report.
The header share button creates a short URL such as /deck/a1b2c3d4, rather than placing the whole compliment deck in the address bar. The recipient can read it immediately or save a copy to their own HypeForge workspace. Each card also has a share panel for the device share sheet, platform-formatted clipboard text, and a locally rendered square PNG; compliment text never needs to be sent to another image service.
Codex and Claude Code were used for implementation support, test generation, UI inspection, and debugging. Product decisions, prompt architecture, security boundaries, validation rules, and acceptance criteria were reviewed in the repository and verified with automated tests plus real Gemini and browser runs.
- Saved personal history and taste signals are local to one browser because the exercise intentionally has no account system.
- Semantic validation is probabilistic even though deterministic checks fail closed around it.
- The signed cookie rate limit is appropriate for a small exercise; a higher-traffic production service should use shared per-IP or account-based throttling.
- Safari coverage uses Playwright WebKit; the final deployed URL should also be checked on a physical iPhone before submission.
- Native share targets and text-to-speech voices depend on browser and operating-system support; unsupported actions fail back to copy or show a clear error.
The next improvement would be user-uploaded company guideline documents that compile into versioned validation rules and visible evidence, extending the same grounded, show-your-work architecture beyond the fixed Brand Team v2.1 document.
Detailed verification commands and coverage are in TESTING.md.