{"id":51850410,"url":"https://github.com/nuuxcode/hypeforge","last_synced_at":"2026-07-23T18:01:28.244Z","repository":{"id":372378696,"uuid":"1297876397","full_name":"nuuxcode/hypeforge","owner":"nuuxcode","description":"Guideline-grounded AI compliment generator with visible 8/8 rule evidence","archived":false,"fork":false,"pushed_at":"2026-07-20T21:13:15.000Z","size":1906,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-20T22:13:53.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hypeforge-liard.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nuuxcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T00:41:27.000Z","updated_at":"2026-07-20T21:13:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nuuxcode/hypeforge","commit_stats":null,"previous_names":["nuuxcode/hypeforge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nuuxcode/hypeforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuuxcode%2Fhypeforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuuxcode%2Fhypeforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuuxcode%2Fhypeforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuuxcode%2Fhypeforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuuxcode","download_url":"https://codeload.github.com/nuuxcode/hypeforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuuxcode%2Fhypeforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35811417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-23T18:01:27.387Z","updated_at":"2026-07-23T18:01:28.236Z","avatar_url":"https://github.com/nuuxcode.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HypeForge - AI Compliment Generator\n\nTurns a job title or person description into three wildly enthusiastic, slightly unhinged compliments.\n\n## Live Demo\n\n[Open HypeForge](https://hypeforge-liard.vercel.app)\n\n![HypeForge showing three independently verified compliment cards](./public/hypeforge-screenshot.png)\n\n## Features\n\n- Exactly three distinct compliments at once, with atomic success and one same-bucket recovery attempt for a failed slot\n- Separate required workplace-function and optional person-details inputs\n- Each card has independent conversation history\n- \"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\n- Copy to clipboard with per-card confirmation and fallback copy support\n- Intentional loading, friendly errors, and mobile-first layout\n- Premium workspace with saved decks, per-card version history, tweak notes, and light taste signals\n- Clean share links at `/deck/\u003cshort-id\u003e` with a public, readable deck page\n- Per-card native sharing, X/LinkedIn/WhatsApp copy formats, and downloadable 1200x1200 PNG cards\n- User-triggered read aloud with the device's built-in speech synthesizer and an immediate stop control\n- Crawlable compliment guide, metadata, Open Graph image, JSON-LD, `robots.txt`, and sitemap\n- Company Compliment Guidelines v2.1 enforced across generation, retry, tweak, and escalation\n- 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\n- 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\n- Independent semantic validator for appearance, metaphor quality, public figures, workplace safety, and escalation quality\n- Deck-wide duplicate, opening, metaphor, statistic, persona-fit, imagery, and humor checks with targeted card regeneration\n- 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\n\n## Tech Stack\n\nNext.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.\n\n## Model Choice\n\nGemini 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.\n\nThe 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](./COMPLIANCE.md).\n\n## Prompt Design\n\nEach 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.\n\nAfter 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.\n\nGemini 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.\n\n## Conversation State\n\nEach 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.\n\n## Environment\n\n```bash\ncp .env.example .env.local\n```\n\nSet `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.\n\nFor 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.\n\nShared 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:\u003cslug\u003e` 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.\n\n## Run Locally\n\n```bash\npnpm install\npnpm dev\n```\n\nOpen http://localhost:3000. The old `/v2` path still works and redirects to the homepage, so previously shared links keep resolving.\n\n## Checks\n\n```bash\npnpm lint\npnpm typecheck\npnpm test\npnpm test:a11y\npnpm test:browsers\npnpm build\npnpm verify:api\npnpm eval:quality\n```\n\n`eval: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.\n\n## Sharing\n\nThe 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.\n\n## AI-Assisted Development\n\nCodex 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.\n\n## Known Limitations\n\n- Saved personal history and taste signals are local to one browser because the exercise intentionally has no account system.\n- Semantic validation is probabilistic even though deterministic checks fail closed around it.\n- 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.\n- Safari coverage uses Playwright WebKit; the final deployed URL should also be checked on a physical iPhone before submission.\n- 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.\n\n## Future Improvement\n\nThe 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.\n\nDetailed verification commands and coverage are in [TESTING.md](./TESTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuuxcode%2Fhypeforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuuxcode%2Fhypeforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuuxcode%2Fhypeforge/lists"}