CoolFace
Apppublic

build-small-hackathon/GenreGoblin

sourceHugging Facemitupdated 3mo agoView on Hugging Face
1likes
App README

GenreGoblin

Plain text goes in. Theater comes out.

GenreGoblin turns everyday messages into copy-ready Shakespearean threats-without-threats, corporate apologies, anime speeches, haunted announcements, royal decrees, and more. It is a polished Gradio Space built for the Build Small Hackathon: Thousand Token Wood track.

Demo video: [add link] Social post: [add link]

Live Space: https://huggingface.co/spaces/build-small-hackathon/GenreGoblin

Trace dataset: https://huggingface.co/datasets/build-small-hackathon/genregoblin-traces

Modal health: https://krishnagaarg--genregoblin-minicpm-minicpmservice-health.modal.run

VoxCPM health: https://krishnagaarg--genregoblin-minicpm-voxcpmservice-health.modal.run

Official Hackathon References

The official registration app lists three rules: models at or below 32B parameters, Gradio plus Hugging Face Spaces, and a demo video plus social post. Submissions are due June 15, 2026 at 23:59 UTC.

What It Does

  1. 1.Enter an ordinary message.
  2. 2.Choose one of 12 genres or write a custom persona.
  3. 3.Set the use-case and theatrical intensity.
  4. 4.Receive a stylized message, short version, Genre DNA, safety estimate, and agent trace.
  5. 5.Continue with another message while preserving the same in-session voice.

The app includes six one-click demos, clipboard controls, instant browser speech, genre-designed VoxCPM2 voices, a share card, and a deterministic fallback so the text demo still works when inference does not.

Small-Model Native

The primary model is `openbmb/MiniCPM3-4B`, a compact 4B-parameter text model with strong instruction-following. GenreGoblin gives the model a compact structured task: preserve intent, apply a genre profile, score the result, and return JSON. The UI then validates and renders that structure.

LayerModel / methodSize
Core generationOpenBMB MiniCPM3-4B4B parameters
Genre voice designOpenBMB VoxCPM22B parameters
Guaranteed fallbackDeterministic Python stylizerNo model
Instant voice fallbackBrowser Speech SynthesisNo server model

No model over 4B parameters is part of the experience.

Inference Modes

GenreGoblin selects the first configured path and safely falls back if it fails:

  1. 1.Hosted MiniCPM using MINICPM_API_URL
  2. 2.Modal MiniCPM3-4B using USE_MODAL=true and MODAL_API_URL
  3. 3.Local Transformers using ENABLE_LOCAL_MODEL=true
  4. 4.Deterministic demo engine with no credentials or model download

Copy .env.example to .env when configuring a backend. Secrets are never hardcoded.

Hosted endpoint

bash
MINICPM_API_URL=https://your-endpoint.example/generate
MINICPM_API_KEY=your-secret
MINICPM_MODEL_ID=openbmb/MiniCPM3-4B

Hugging Face-style inputs endpoints work by default. For OpenAI-compatible endpoints, set MINICPM_API_FORMAT=openai or use a URL containing chat/completions.

Local MiniCPM

Local inference is deliberately opt-in because Torch and model weights make a Space heavier.

bash
pip install -r requirements-local.txt
ENABLE_LOCAL_MODEL=true python app.py

Modal

`modal_app.py` is the production GPU endpoint. The main app recovers to deterministic mode if Modal is unavailable, so an inference outage cannot break the demo.

The deployment runs MiniCPM3-4B on a Modal T4 and VoxCPM2 on a Modal L4, both with a persistent model cache. Their public health responses are linked near the top of this README.

bash
pip install modal
modal setup
modal deploy modal_app.py

Set the deployed endpoint URL:

bash
USE_MODAL=true
MODAL_API_URL=https://your-workspace--genregoblin-minicpm-minicpmservice-generate.modal.run
VOXCPM_API_URL=https://your-workspace--genregoblin-minicpm-voxcpmservice-generate.modal.run

Genre Voice Design

Every built-in genre has a distinct natural-language voice direction. The haunted railway uses a measured vintage announcer with unsettling pauses, while film noir uses a tired low narrator with dry sarcasm. VoxCPM2 receives the direction plus generated text and returns a 48 kHz WAV. No real person's voice is cloned.

Voice generation is user-triggered because VoxCPM2 is a diffusion TTS model. Warm generation takes roughly ten seconds in the deployed configuration; a fully cold container can take several minutes to load and compile. Instant preview remains available through browser speech while the studio voice is cold.

Run Locally

bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

On Windows PowerShell:

powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -r requirements.txt
py app.py

Open http://localhost:7860. No API key is required for the fallback demo.

Run the offline smoke suite with:

bash
python smoke_test.py
python quality_eval.py

quality_eval.py checks all 12 genres, 10 use cases, and five intensity levels: 600 combinations covering intent retention, genre vocabulary, forbidden words, channel length, short-version behavior, and output distinctness.

Deploy to Hugging Face Spaces

  1. 1.Create a new Gradio Space.
  2. 2.Push this repository to the Space.
  3. 3.Optionally add MINICPM_API_URL, MINICPM_API_KEY, or Modal values as Space secrets.
  4. 4.Keep no model secrets configured to run the instant deterministic demo.

The README frontmatter configures app.py as the Space entry point.

Agentic Experience

Each rewrite exposes an honest Goblin Agent Trace:

  • —Read plain intent
  • —Apply genre lens
  • —Preserve original meaning
  • —Adjust intensity
  • —Run a sendability check
  • —Add final polish

GoblinRewriteAgent runs an actual bounded agent loop: build a grounded draft plan, call the MiniCPM tool, parse its structured result, validate intent and safety, send one autonomous repair instruction when needed, then recover deterministically if the repair still fails. The generated Genre DNA stores vocabulary, rhythm, forbidden words, a signature phrase, and emotional temperature. Recent outputs are passed back as style memory during follow-ups.

Reliability and Safety

  • —Model output is requested as JSON and parsed defensively.
  • —Invalid JSON, network failures, and missing packages all recover to deterministic output.
  • —Unsafe requests are converted into non-threatening boundary-setting alternatives.
  • —User text is escaped before being placed in custom HTML.
  • —Sendability is a playful estimate, not a guarantee of appropriateness.

Official Quest Eligibility

TargetHow GenreGoblin addresses it
Thousand Token WoodWhimsical, useful AI-native message transformation
OpenBMBMiniCPM3-4B is the primary generation model
Tiny TitanMiniCPM3-4B and VoxCPM2 are both at or below 4B parameters
ModalText runs on a Modal T4 and genre voice design runs on a Modal L4
Off-BrandFully custom parchment, neon green, purple-shadow Gradio design
Best AgentGoblinRewriteAgent performs model-tool calls, validation, an autonomous repair pass, and recovery
Sharing is CaringSynthetic trace examples and evaluation artifacts are published publicly
Field NotesBuild decisions and small-model lessons are documented in FIELD_NOTES.md

Not claimed: Off the Grid (Modal is remote), Well-Tuned (no LoRA yet), Llama Champion (no llama.cpp runtime), Backyard AI (the primary track is whimsical), and Nemotron (no NVIDIA model in the current flow).

OpenAI Codex Sponsor Prize

GenreGoblin also targets Best Use of Codex, a sponsor prize separate from the official 13-dimension quest classifier. The official-organization sponsor notes define the requirement as Codex-attributed commits in the connected GitHub repository or Space.

Codex implemented and tested the rewrite agent, genre quality system, VoxCPM2 integration, Modal deployment, UI refinement, evaluation scripts, and submission documentation. Final Space commits include the standard Co-authored-by: Codex <codex@openai.com> trailer.

Demo Script

  1. 1.Click I'm running late to reveal the haunted railway announcement.
  2. 2.Point out the sendability and chaos meters.
  3. 3.Open Behind the rewrite, then briefly show the agent trace.
  4. 4.Enter Please bring snacks too under Continue in the same voice.
  5. 5.Use Instant preview, then Generate genre voice to compare browser and VoxCPM2 speech.
  6. 6.Open the share card and copy its social text.
  7. 7.Switch to Anime Power-Up Speech, intensity 5, for the finale.
  8. 8.Mention MiniCPM3-4B + VoxCPM2 on Modal, all models at or below 4B, and deterministic recovery.

Structure

text
app.py                  Gradio UI, model adapters, fallback engine, state, rendering
modal_app.py            Production Modal text and VoxCPM2 voice endpoints
smoke_test.py           Offline checks for genres, safety, JSON, and continuity
evaluate.py             Reproducible seven-case product evaluation
quality_eval.py         600-case genre/use-case/intensity quality matrix
FIELD_NOTES.md          Build journal and small-model lessons
SUBMISSION.md           Final links, prize claims, and demo checklist
SOCIAL_POST.md          Ready-to-publish social post draft
data/                   Synthetic privacy-safe agent trace examples
requirements.txt        Lightweight default Space dependencies
requirements-local.txt  Optional Transformers/Torch dependencies
.env.example            Backend configuration template

Codex Attribution

OpenAI Codex was used for implementation, prompt design, deterministic genre writing, custom Gradio UI polish, safety/recovery behavior, and local evaluation scripts/checks.

License

MIT