feat:all

README.md

@@ -1,13 +1,78 @@
+# MiniCPM-V 4.6 · An Adventure in Thousand Token Wood
+
+API-powered image description using OpenBMB's hosted MiniCPM-V 4.6.  
+No model download. No GPU. Works on any machine with internet access.
+
+---
+
+## Quick start
+
+```bash
+pip install -r requirements.txt
+python main.py
+# → http://localhost:7860
+```
+
+---
+
+## File structure
+
+```
+minicpm_app/
+├── main.py                  ← entry point  (python main.py)
+├── requirements.txt
+│
+├── config/
+│   ├── __init__.py
+│   └── settings.py          ← API URL, keys, model IDs, defaults
+│
+├── core/
+│   ├── __init__.py
+│   ├── api_client.py        ← streaming API call + error handling
+│   └── image_utils.py       ← PIL → JPEG → base64 data URL
+│
+└── ui/
+    ├── __init__.py
+    ├── app.py               ← Gradio layout (build_ui)
+    └── components.py        ← individual input/output widgets
+```
+
+---
+
+## Models
+
+| Model                    | Params | Best for                         |
+| ------------------------ | ------ | -------------------------------- |
+| `MiniCPM-V-4.6-Instruct` | 1.3 B  | Fast Q&A, direct descriptions    |
+| `MiniCPM-V-4.6-Thinking` | 1.3 B  | Complex reasoning, OCR, analysis |
+
+Both are well under the 32 B parameter cap.
+
 ---
-title: Hackathon
-emoji: 🏆
-colorFrom: gray
-colorTo: purple
-sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
+
+## API key
+
+A **free public key** is baked into `config/settings.py` — works immediately, no signup.
+
+For higher rate limits, get a personal key at https://modelbest.cn and either:
+
+- Paste it in the **API Key** field in the UI, or
+- Set the environment variable:
+  ```bash
+  export MINICPM_API_KEY=sk-your-key-here
+  python main.py
+  ```
+
+Priority: `MINICPM_API_KEY` env var → UI field → public fallback key.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Extending
+
+| Task                         | File to edit                             |
+| ---------------------------- | ---------------------------------------- |
+| Change model / add new model | `config/settings.py` → `MODELS` dict     |
+| Adjust defaults              | `config/settings.py` → `DEFAULT_*`       |
+| Change API endpoint          | `config/settings.py` → `API_BASE_URL`    |
+| Add retry logic / logging    | `core/api_client.py`                     |
+| Add new UI widgets           | `ui/components.py` + wire in `ui/app.py` |

app_single.py

@@ -0,0 +1,793 @@
+"""
+app_single.py — MiniCPM-V 4.6 · Emberglade
+==================================================
+A vision-language playground: MiniCPM-V describes an uploaded image,
+then choreographs a cat to perform that mood on a spotlight stage.
+
+Pipeline:
+  1. Upload image → MiniCPM-V streams a description
+  2. Model returns a JSON dance spec (mood + 6 numeric animation params)
+  3. The cat performs on stage using those exact params — every move
+     is model-determined, not hardcoded.
+
+Dance params returned by model:
+  mood        : one of 10 mood words
+  speed       : animation cycle seconds (0.3 fast … 3.0 slow)
+  jump        : vertical bounce px (0 … 60)
+  sway        : body rotation degrees (0 … 20)
+  tail_speed  : tail cycle seconds (0.2 … 3.0)
+  tail_range  : tail swing degrees (5 … 120)
+  ear_tilt    : ear rotation degrees (0 … 25)
+
+Run locally:
+  pip install -r requirements.txt
+  python app_single.py
+  → open http://localhost:7860
+
+  Optional: set your own API key so you're not on the shared public quota
+    Windows (PowerShell):  $env:MINICPM_API_KEY="sk-..."
+    macOS / Linux:         export MINICPM_API_KEY="sk-..."
+"""
+
+import base64, io, os, json, re
+import gradio as gr
+from openai import OpenAI, APIStatusError, APIConnectionError
+from PIL import Image
+
+# ── Config ────────────────────────────────────────────────────────────────────
+API_BASE_URL   = "https://api.modelbest.cn/v1"
+PUBLIC_API_KEY = "sk-pQ8L2zF3XmR5kY9wV4jB7hN1tC6vM0xG3aD5sH2bJ9lK4cZ8"
+
+MODELS = {
+    "⚡ Instruct  (fast, direct)":  "MiniCPM-V-4.6-Instruct",
+    "🧠 Thinking  (reasons first)": "MiniCPM-V-4.6-Thinking",
+}
+
+DEFAULT_PROMPT      = "Describe this image in detail."
+DEFAULT_MAX_TOKENS  = 512
+DEFAULT_TEMPERATURE = 0.7
+IMAGE_QUALITY       = 90
+
+MOOD_LABELS = ["happy","sad","calm","energetic","mysterious",
+               "romantic","tense","nostalgic","angry","neutral"]
+
+PROMPT_EXAMPLES = [
+    ["Describe this image in detail."],
+    ["List every object you can see."],
+    ["What is the mood or atmosphere of this image?"],
+    ["What text, if any, appears in this image?"],
+    ["Explain this image to someone who cannot see it."],
+]
+
+# ── Mood palettes — each mood is a "spotlight color" on the dark stage ────────
+MOOD_PALETTE = {
+    "happy":      {"bg":"#1a1605","body":"#FFD166","detail":"#E8A23A","eye":"#2D1B00","nose":"#FF8A3D","pcol":"#FFE08A","particle":"✦","label":"Happy","caption":"Bouncing with joy"},
+    "sad":        {"bg":"#0c1116","body":"#8AA0B2","detail":"#5D7A8E","eye":"#1A2530","nose":"#B7C7D2","pcol":"#A9C8E0","particle":"·","label":"Sad","caption":"Slow, heavy steps"},
+    "calm":       {"bg":"#0a1614","body":"#6FBFB3","detail":"#4A9C8F","eye":"#0A2018","nose":"#A8E0D6","pcol":"#BFEDE4","particle":"○","label":"Calm","caption":"Drifting at ease"},
+    "energetic":  {"bg":"#1a0e05","body":"#FF8A5B","detail":"#E8623A","eye":"#1a0500","nose":"#FFD1BC","pcol":"#FFCB6B","particle":"★","label":"Energetic","caption":"Can't sit still"},
+    "mysterious": {"bg":"#120c1a","body":"#A98BD6","detail":"#6D4FA8","eye":"#F0B8FF","nose":"#D9C2EE","pcol":"#C7B3F0","particle":"✧","label":"Mysterious","caption":"Slipping through shadow"},
+    "romantic":   {"bg":"#1a0c12","body":"#F2A0BD","detail":"#D9648D","eye":"#1a0010","nose":"#FBE0EA","pcol":"#F7B8CE","particle":"♥","label":"Romantic","caption":"A slow, dreamy waltz"},
+    "tense":      {"bg":"#100808","body":"#F0726E","detail":"#C03C38","eye":"#FFB3AE","nose":"#F7C7C4","pcol":"#F2A6A2","particle":"|","label":"Tense","caption":"Coiled and alert"},
+    "nostalgic":  {"bg":"#160f06","body":"#F2C083","detail":"#D98A3D","eye":"#160f06","nose":"#FBE3C7","pcol":"#F7DDB5","particle":"◦","label":"Nostalgic","caption":"Rocking to old memories"},
+    "angry":      {"bg":"#160505","body":"#F0635E","detail":"#A8201C","eye":"#FF6961","nose":"#F7B0AC","pcol":"#F58F8A","particle":"✸","label":"Angry","caption":"Stomping, full of fire"},
+    "neutral":    {"bg":"#0e0f13","body":"#A6ADB8","detail":"#727A86","eye":"#0d0d18","nose":"#D8DDE3","pcol":"#C7CDD6","particle":"·","label":"Neutral","caption":"Steady and unhurried"},
+}
+
+# ── Default dance specs (fallback if model call fails) ────────────────────────
+DEFAULT_DANCE = {
+    "happy":      {"speed":0.7, "jump":50, "sway":6,  "tail_speed":0.4, "tail_range":200,"ear_tilt":8},
+    "sad":        {"speed":2.4, "jump":2,  "sway":8,  "tail_speed":2.5, "tail_range":30, "ear_tilt":15},
+    "calm":       {"speed":2.8, "jump":10, "sway":2,  "tail_speed":3.2, "tail_range":35, "ear_tilt":3},
+    "energetic":  {"speed":0.3, "jump":30, "sway":15, "tail_speed":0.28,"tail_range":180,"ear_tilt":15},
+    "mysterious": {"speed":2.0, "jump":15, "sway":5,  "tail_speed":1.8, "tail_range":100,"ear_tilt":5},
+    "romantic":   {"speed":1.6, "jump":12, "sway":5,  "tail_speed":1.6, "tail_range":65, "ear_tilt":3},
+    "tense":      {"speed":0.4, "jump":3,  "sway":3,  "tail_speed":0.4, "tail_range":10, "ear_tilt":12},
+    "nostalgic":  {"speed":2.2, "jump":6,  "sway":6,  "tail_speed":2.0, "tail_range":65, "ear_tilt":5},
+    "angry":      {"speed":0.38,"jump":18, "sway":5,  "tail_speed":0.32,"tail_range":160,"ear_tilt":20},
+    "neutral":    {"speed":2.0, "jump":8,  "sway":1,  "tail_speed":2.2, "tail_range":30, "ear_tilt":2},
+}
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+def pil_to_data_url(image):
+    image = image.convert("RGB")
+    buf = io.BytesIO()
+    image.save(buf, format="JPEG", quality=IMAGE_QUALITY)
+    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
+
+def _resolve_key(ui_key):
+    return (os.environ.get("MINICPM_API_KEY","").strip()
+            or (ui_key or "").strip() or PUBLIC_API_KEY)
+
+def _client(ui_key):
+    return OpenAI(api_key=_resolve_key(ui_key), base_url=API_BASE_URL)
+
+# ── Description (streaming) ───────────────────────────────────────────────────
+def stream_description(image, prompt, model_label, max_tokens, temperature, api_key):
+    if image is None:
+        yield "⚠️  Please upload an image first."
+        return
+    try:
+        stream = _client(api_key).chat.completions.create(
+            model=MODELS[model_label],
+            messages=[{"role":"user","content":[
+                {"type":"image_url","image_url":{"url": pil_to_data_url(image)}},
+                {"type":"text","text": prompt},
+            ]}],
+            max_tokens=max_tokens, temperature=temperature, stream=True,
+        )
+        result = ""
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content or ""
+            if delta:
+                result += delta
+                yield result
+    except APIStatusError as e:
+        yield f"❌ API error {e.status_code}: {e.message}"
+    except APIConnectionError:
+        yield "❌ Cannot reach api.modelbest.cn"
+    except Exception as e:
+        yield f"❌ {e}"
+
+# ── Model-driven dance spec ───────────────────────────────────────────────────
+DANCE_SYSTEM_PROMPT = f"""You are a cat dance choreographer AI.
+Given a scene description, return ONLY a valid JSON object — no prose, no markdown, no code fences.
+
+JSON schema (all fields required):
+{{
+  "mood":       one of {MOOD_LABELS},
+  "speed":      float 0.3–3.0  (animation cycle seconds; lower = faster),
+  "jump":       int   0–60     (vertical bounce in pixels),
+  "sway":       int   0–20     (body rotation degrees),
+  "tail_speed": float 0.2–3.0  (tail cycle seconds),
+  "tail_range": int   5–200    (tail swing degrees),
+  "ear_tilt":   int   0–25     (ear tilt degrees)
+}}
+
+Choose values that physically match the scene mood. An energetic scene should have
+low speed (fast), high jump, high sway. A calm scene should have high speed (slow),
+low jump, low sway. Be creative — the cat's whole body expresses the image's emotion."""
+
+def get_dance_spec(description: str, api_key: str) -> tuple[str, dict]:
+    """
+    Returns (mood, dance_params_dict).
+    The model outputs the full dance spec as JSON.
+    Falls back to defaults if parsing fails.
+    """
+    if not description or description.startswith(("⚠️","❌")):
+        return "neutral", DEFAULT_DANCE["neutral"]
+    try:
+        resp = _client(api_key).chat.completions.create(
+            model="MiniCPM-V-4.6-Instruct",
+            messages=[
+                {"role":"system","content": DANCE_SYSTEM_PROMPT},
+                {"role":"user",  "content": f"Scene description:\n{description[:800]}"},
+            ],
+            max_tokens=120, temperature=0.3,
+        )
+        raw = resp.choices[0].message.content.strip()
+        # Strip markdown fences if present
+        raw = re.sub(r"```[a-z]*", "", raw).strip().strip("`").strip()
+        spec = json.loads(raw)
+
+        mood = spec.get("mood","neutral")
+        if mood not in MOOD_LABELS:
+            mood = "neutral"
+
+        dance = {
+            "speed":      float(max(0.3, min(3.0, spec.get("speed", 1.5)))),
+            "jump":       int(max(0,   min(60,  spec.get("jump",  10)))),
+            "sway":       int(max(0,   min(20,  spec.get("sway",  5)))),
+            "tail_speed": float(max(0.2, min(3.0, spec.get("tail_speed", 1.5)))),
+            "tail_range": int(max(5,   min(200, spec.get("tail_range", 40)))),
+            "ear_tilt":   int(max(0,   min(25,  spec.get("ear_tilt",  5)))),
+        }
+        return mood, dance
+
+    except Exception:
+        # keyword fallback for mood, default params
+        t = description.lower()
+        mood = "neutral"
+        for m, kws in [
+            ("happy",["happy","joy","celebrate","laugh","smile","bright","sunny"]),
+            ("sad",["sad","lonely","rain","sorrow","grief","cry","gloom"]),
+            ("energetic",["energetic","vibrant","excited","dynamic","rush","active"]),
+            ("calm",["calm","peaceful","quiet","gentle","serene","still"]),
+            ("mysterious",["mysterious","dark","eerie","shadow","mystic","fog"]),
+            ("romantic",["romantic","love","tender","intimate","warm","soft"]),
+            ("tense",["tense","anxious","fear","alarm","nervous","danger"]),
+            ("nostalgic",["nostalgic","memory","vintage","old","past","retro"]),
+            ("angry",["angry","furious","rage","fierce","storm"]),
+        ]:
+            if any(w in t for w in kws):
+                mood = m
+                break
+        return mood, DEFAULT_DANCE[mood]
+
+# ── Keyword dance for text-only tab (no API needed) ───────────────────────────
+def generate_animation(text: str) -> str:
+    t = text.lower()
+    mood = "neutral"
+    for m, kws in [
+        ("happy",["happy","celebrate","party","joy","cheerful"]),
+        ("sad",["sad","lonely","rain","grief","sorrow"]),
+        ("energetic",["energy","dance","excited","lively"]),
+        ("calm",["calm","peace","serene","gentle","quiet"]),
+        ("mysterious",["mysterious","eerie","dark","shadow"]),
+        ("romantic",["romantic","love","tender","warm"]),
+        ("tense",["tense","nervous","anxiety","fear"]),
+        ("nostalgic",["nostalgic","memory","vintage","old"]),
+        ("angry",["angry","furious","rage","fierce"]),
+    ]:
+        if any(w in t for w in kws):
+            mood = m
+            break
+    return cat_html(mood, DEFAULT_DANCE[mood])
+
+# ── Stage chrome — shared studio frame ────────────────────────────────────────
+STAGE_FONT = "'Space Grotesk', 'Inter', system-ui, sans-serif"
+MONO_FONT  = "'JetBrains Mono', 'SFMono-Regular', Consolas, monospace"
+
+def _stage_open(spotlight_color: str, breathe_speed: float = 4.0) -> str:
+    """Opening <div> + shared <style> for the stage frame with a breathing spotlight."""
+    return f"""<div class="stage" style="--spot:{spotlight_color};">
+<style>
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+.stage {{
+  position:relative; height:440px; border-radius:16px;
+  overflow:hidden; isolation:isolate;
+  background:
+    radial-gradient(ellipse 70% 55% at 50% 28%, color-mix(in srgb, var(--spot) 22%, transparent), transparent 70%),
+    linear-gradient(180deg, #11141b 0%, #0B0E14 100%);
+  border:1px solid #1E2430;
+  display:flex; flex-direction:column; align-items:center; justify-content:center;
+  font-family:{STAGE_FONT};
+}}
+@keyframes spot_breathe {{
+  0%,100% {{ opacity:.85; }}
+  50%     {{ opacity:1; }}
+}}
+.stage::before {{
+  content:''; position:absolute; inset:0; pointer-events:none;
+  background: radial-gradient(ellipse 45% 38% at 50% 22%, color-mix(in srgb, var(--spot) 30%, transparent), transparent 72%);
+  animation: spot_breathe {breathe_speed}s ease-in-out infinite;
+  mix-blend-mode: screen;
+}}
+.stage::after {{
+  content:''; position:absolute; inset:0; pointer-events:none;
+  background-image:
+    repeating-linear-gradient(0deg,  rgba(255,255,255,.012) 0px, rgba(255,255,255,.012) 1px, transparent 1px, transparent 3px),
+    repeating-linear-gradient(90deg, rgba(255,255,255,.012) 0px, rgba(255,255,255,.012) 1px, transparent 1px, transparent 3px);
+}}
+
+.stage-cue {{
+  position:absolute; top:18px; left:0; right:0;
+  display:flex; align-items:center; justify-content:center; gap:10px;
+  font-size:.72rem; letter-spacing:.22em; text-transform:uppercase;
+  color:#9CA3AF; font-weight:500; z-index:3;
+}}
+.stage-cue .dot {{
+  width:7px; height:7px; border-radius:50%;
+  background:var(--spot); box-shadow:0 0 8px var(--spot);
+}}
+.stage-cue .mood-name {{
+  color:#F5F1E8; font-weight:700; letter-spacing:.14em;
+}}
+
+.stage-caption {{
+  position:absolute; bottom:46px; left:0; right:0; text-align:center; z-index:3;
+  color:#9CA3AF; font-size:.82rem; letter-spacing:.03em; font-style:italic;
+}}
+
+.cue-sheet {{
+  position:absolute; bottom:14px; left:0; right:0; z-index:3;
+  display:flex; justify-content:center; gap:14px; flex-wrap:wrap;
+  padding:0 20px;
+}}
+.cue-chip {{
+  font-family:{MONO_FONT}; font-size:.66rem; letter-spacing:.04em;
+  color:#9CA3AF; background:#13171F; border:1px solid #1E2430;
+  border-radius:6px; padding:3px 9px; white-space:nowrap;
+}}
+.cue-chip b {{ color:var(--spot); font-weight:500; }}
+</style>
+"""
+
+def _stage_close() -> str:
+    return "</div>"
+
+# ── Cat stage — all parts stay inside the stage, nothing can overflow ─────────
+def cat_html(mood: str, dance: dict) -> str:
+    p   = MOOD_PALETTE.get(mood, MOOD_PALETTE["neutral"])
+    B   = p["body"]; D = p["detail"]; E = p["eye"]; N = p["nose"]
+    sp  = dance["speed"];      jp  = dance["jump"]
+    sw  = dance["sway"];       tsp = dance["tail_speed"]
+    tr  = dance["tail_range"]; et  = dance["ear_tilt"]
+
+    t0 = -tr // 2;  t1 = tr // 2
+    breathe = max(2.0, min(6.0, sp * 2))
+
+    cue_chips = (
+        f'<span class="cue-chip">speed <b>{sp}s</b></span>'
+        f'<span class="cue-chip">jump <b>{jp}px</b></span>'
+        f'<span class="cue-chip">sway <b>{sw}°</b></span>'
+        f'<span class="cue-chip">tail <b>{tsp}s / {tr}°</b></span>'
+        f'<span class="cue-chip">ears <b>{et}°</b></span>'
+    )
+
+    return _stage_open(B, breathe) + f"""
+<style>
+@keyframes K_body {{
+  0%,100% {{ transform: translateY(0px)     rotate(-{sw}deg); }}
+  50%     {{ transform: translateY(-{jp}px) rotate({sw}deg);  }}
+}}
+@keyframes K_tail {{
+  0%,100% {{ transform: rotate({t0}deg); }}
+  50%     {{ transform: rotate({t1}deg); }}
+}}
+@keyframes K_ear {{
+  0%,100% {{ transform: rotate(-{et}deg); }}
+  50%     {{ transform: rotate({et}deg);  }}
+}}
+@keyframes K_blink {{
+  0%,88%,100% {{ transform: scaleY(1);    }}
+  93%         {{ transform: scaleY(0.08); }}
+}}
+@keyframes K_shadow {{
+  0%,100% {{ transform: translateX(-50%) scaleX(1);    opacity:.45; }}
+  50%     {{ transform: translateX(-50%) scaleX({max(0.4, 1 - jp/80):.2f}); opacity:.15; }}
+}}
+@keyframes K_part {{
+  0%   {{ opacity:0;  transform:translate(0,0)         scale(.5); }}
+  20%  {{ opacity:.9;                                              }}
+  80%  {{ opacity:.4;                                              }}
+  100% {{ opacity:0;  transform:translate(var(--px),var(--py)) scale(1.5); }}
+}}
+
+.cat-wrap   {{ position:relative; width:160px; height:200px; z-index:2; }}
+
+.cat-shadow {{
+  position:absolute; bottom:-4px; left:50%;
+  width:72px; height:11px; border-radius:50%;
+  background:rgba(0,0,0,.55);
+  animation: K_shadow {sp}s ease-in-out infinite;
+}}
+
+.cat-unit {{
+  position:absolute; bottom:0; left:50%;
+  transform-origin: center bottom;
+  animation: K_body {sp}s ease-in-out infinite;
+}}
+
+.c-body {{
+  position:absolute; bottom:0; left:-36px;
+  width:72px; height:62px;
+  border-radius:52% 52% 46% 46%;
+  background:{B};
+  box-shadow:inset -6px -5px 0 {D};
+}}
+.c-belly {{
+  position:absolute; bottom:5px; left:50%; transform:translateX(-50%);
+  width:40px; height:30px; border-radius:50%;
+  background:{D}28;
+}}
+
+.c-tail {{
+  position:absolute; bottom:4px; left:22px;
+  width:16px; height:52px;
+  border-radius:38% 62% 55% 45% / 28% 28% 72% 72%;
+  background:{B};
+  box-shadow:inset 3px 0 0 {D};
+  transform-origin:bottom center;
+  animation:K_tail {tsp}s ease-in-out infinite;
+}}
+.c-tail::after {{
+  content:'';
+  position:absolute; top:-9px; left:-5px;
+  width:26px; height:18px; border-radius:50%;
+  background:{B};
+  box-shadow:inset 2px -2px 0 {D};
+}}
+
+.c-paw-l,.c-paw-r {{
+  position:absolute; bottom:0;
+  width:22px; height:13px;
+  border-radius:50% 50% 42% 42%;
+  background:{B};
+  box-shadow:inset -2px -2px 0 {D};
+}}
+.c-paw-l {{ left:-34px; }}
+.c-paw-r {{ left:12px;  }}
+
+.c-head {{
+  position:absolute; bottom:56px; left:-32px;
+  width:64px; height:58px; border-radius:50%;
+  background:{B};
+  box-shadow:inset -4px -3px 0 {D};
+  overflow:visible;
+}}
+
+.c-ear-l,.c-ear-r {{
+  position:absolute;
+  width:0; height:0;
+  border-left:11px solid transparent;
+  border-right:11px solid transparent;
+  border-bottom:21px solid {B};
+  animation:K_ear {sp}s ease-in-out infinite;
+}}
+.c-ear-l {{ top:-16px; left:2px;  transform-origin:bottom left;  }}
+.c-ear-r {{ top:-16px; left:40px; transform-origin:bottom right; }}
+.c-ear-l::after,.c-ear-r::after {{
+  content:'';position:absolute;top:5px;left:-6px;
+  width:0;height:0;
+  border-left:6px solid transparent;
+  border-right:6px solid transparent;
+  border-bottom:13px solid {D};
+}}
+
+.c-eye-l,.c-eye-r {{
+  position:absolute;
+  width:12px; height:12px; border-radius:50%;
+  background:{E};
+  animation:K_blink 3.5s ease-in-out infinite;
+}}
+.c-eye-l {{ top:18px; left:8px;  }}
+.c-eye-r {{ top:18px; left:44px; animation-delay:.2s; }}
+.c-eye-l::after,.c-eye-r::after {{
+  content:'';position:absolute;top:2px;left:2px;
+  width:5px;height:5px;border-radius:50%;
+  background:rgba(255,255,255,.32);
+}}
+
+.c-nose {{
+  position:absolute; top:32px; left:27px;
+  width:10px; height:7px;
+  border-radius:50% 50% 40% 40%;
+  background:{N};
+  transform:translateX(-50%);
+}}
+
+.c-mouth-l,.c-mouth-r {{
+  position:absolute;
+  width:8px; height:5px;
+  border:0 solid {N};
+  border-bottom-width:1.5px;
+  border-radius:0 0 50% 50%;
+  top:38px;
+}}
+.c-mouth-l {{ left:21px; border-left-width:1.5px;  transform:rotate(10deg);  }}
+.c-mouth-r {{ left:30px; border-right-width:1.5px; transform:rotate(-10deg); }}
+
+.c-wl1,.c-wl2,.c-wr1,.c-wr2 {{
+  position:absolute; height:1.5px;
+  background:rgba(255,255,255,.5); border-radius:1px;
+  width:28px;
+}}
+.c-wl1 {{ top:29px; right:37px; transform:rotate(-10deg); transform-origin:right; }}
+.c-wl2 {{ top:35px; right:37px; transform:rotate( 10deg); transform-origin:right; }}
+.c-wr1 {{ top:29px; left:37px;  transform:rotate( 10deg); transform-origin:left;  }}
+.c-wr2 {{ top:35px; left:37px;  transform:rotate(-10deg); transform-origin:left;  }}
+
+.c-particle {{
+  position:absolute; pointer-events:none;
+  color:{p['pcol']}; font-size:.9rem;
+  text-shadow:0 0 4px {p['pcol']};
+  opacity:0;
+  animation:K_part var(--pd) var(--pde) ease-out infinite;
+}}
+</style>
+
+<div class="stage-cue">
+  <span class="dot"></span>
+  <span class="mood-name">{p['label']}</span>
+  <span>&nbsp;·&nbsp;now performing</span>
+</div>
+
+<div class="cat-wrap" id="cw">
+  <div class="cat-shadow"></div>
+  <div class="cat-unit">
+    <div class="c-tail"></div>
+    <div class="c-body"><div class="c-belly"></div></div>
+    <div class="c-paw-l"></div>
+    <div class="c-paw-r"></div>
+    <div class="c-head">
+      <div class="c-ear-l"></div>
+      <div class="c-ear-r"></div>
+      <div class="c-eye-l"></div>
+      <div class="c-eye-r"></div>
+      <div class="c-nose"></div>
+      <div class="c-mouth-l"></div>
+      <div class="c-mouth-r"></div>
+      <div class="c-wl1"></div>
+      <div class="c-wl2"></div>
+      <div class="c-wr1"></div>
+      <div class="c-wr2"></div>
+    </div>
+  </div>
+</div>
+
+<div class="stage-caption">{p['caption']}</div>
+<div class="cue-sheet">{cue_chips}</div>
+
+<script>
+(function(){{
+  const wrap = document.getElementById('cw');
+  const chars = '{p['particle']}'.split('');
+  for(let i=0;i<22;i++){{
+    const el = document.createElement('div');
+    el.className = 'c-particle';
+    el.textContent = chars[i % chars.length];
+    const a = Math.random()*Math.PI*2, d = 50+Math.random()*75;
+    el.style.setProperty('--px', (Math.cos(a)*d)+'px');
+    el.style.setProperty('--py', (Math.sin(a)*d-20)+'px');
+    el.style.setProperty('--pd', (.9+Math.random()*2).toFixed(2)+'s');
+    el.style.setProperty('--pde',(Math.random()*2.5).toFixed(2)+'s');
+    el.style.left = (55+Math.random()*50)+'px';
+    el.style.top  = (40+Math.random()*80)+'px';
+    el.style.fontSize = (.55+Math.random()*.65).toFixed(2)+'rem';
+    wrap.appendChild(el);
+  }}
+}})();
+</script>""" + _stage_close()
+
+def placeholder_html():
+    return _stage_open("#9CA3AF", 6.0) + f"""
+<div style="text-align:center; z-index:2; color:#9CA3AF; font-family:{STAGE_FONT};">
+  <div style="font-size:2.4rem; margin-bottom:14px; opacity:.35;">🐾</div>
+  <div style="font-size:.95rem; font-weight:700; letter-spacing:.05em; color:#F5F1E8; margin-bottom:6px;">
+    Waiting for a performance
+  </div>
+  <div style="font-size:.78rem; color:#6B7280; max-width:260px; margin:0 auto; line-height:1.6;">
+    Upload an image — the model reads its mood and choreographs every move the cat makes.
+  </div>
+</div>""" + _stage_close()
+
+def loading_html() -> str:
+    return _stage_open("#FF8A3D", 2.0) + f"""
+<div style="text-align:center; z-index:2; color:#9CA3AF; font-family:{STAGE_FONT};">
+  <div class="loading-spinner" style="
+    width:34px; height:34px; margin:0 auto 16px;
+    border:3px solid #1E2430; border-top-color:#FF8A3D;
+    border-radius:50%; animation: spin 0.9s linear infinite;"></div>
+  <div style="font-size:.85rem; letter-spacing:.06em; color:#F5F1E8; font-weight:700;">
+    Reading the room…
+  </div>
+  <div style="font-size:.74rem; color:#6B7280; margin-top:4px;">
+    choreographing the next performance
+  </div>
+</div>
+<style>@keyframes spin {{ to {{ transform: rotate(360deg); }} }}</style>""" + _stage_close()
+
+# ── Main pipeline ─────────────────────────────────────────────────────────────
+def run_image_pipeline(image, prompt, model_label, max_tokens, temperature, api_key):
+    final_desc = ""
+    for partial in stream_description(image, prompt, model_label, max_tokens, temperature, api_key):
+        final_desc = partial
+        yield partial, loading_html()
+
+    # Model determines the full dance spec
+    mood, dance = get_dance_spec(final_desc, api_key)
+    yield final_desc, cat_html(mood, dance)
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# UI — Emberglade
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap');
+
+:root {
+  --bg:        #0B0E14;
+  --surface:   #13171F;
+  --raised:    #1E2430;
+  --text:      #F5F1E8;
+  --text-dim:  #9CA3AF;
+  --text-faint:#6B7280;
+  --accent:    #FF8A3D;
+}
+
+.gradio-container {
+  background: var(--bg) !important;
+  font-family: 'Inter', system-ui, sans-serif !important;
+}
+
+/* ── Header ────────────────────────────────────────────────────────────── */
+#studio-header {
+  text-align:center; padding: 8px 0 4px;
+}
+#studio-header h1 {
+  font-family:'Space Grotesk', sans-serif !important;
+  font-weight:700 !important; letter-spacing:.01em;
+  font-size:1.9rem !important; color:var(--text) !important;
+  margin-bottom:4px !important;
+}
+#studio-header p {
+  color:var(--text-dim) !important; font-size:.92rem !important;
+  margin:0 !important;
+}
+#studio-header .eyebrow {
+  display:inline-flex; align-items:center; gap:8px;
+  font-family:'JetBrains Mono', monospace; font-size:.7rem;
+  letter-spacing:.22em; text-transform:uppercase;
+  color:var(--accent); margin-bottom:10px;
+}
+#studio-header .eyebrow .line {
+  width:28px; height:1px; background:var(--accent); opacity:.5;
+}
+
+/* ── Panels ────────────────────────────────────────────────────────────── */
+.gr-form, .gr-box, .gr-panel, .gr-block.gr-box {
+  background: var(--surface) !important;
+  border: 1px solid var(--raised) !important;
+  border-radius: 12px !important;
+}
+
+/* Section labels */
+.gradio-container label span {
+  font-family:'Inter', sans-serif !important;
+  font-size:.78rem !important; font-weight:600 !important;
+  letter-spacing:.04em !important; color:var(--text-dim) !important;
+}
+
+/* ── Buttons ───────────────────────────────────────────────────────────── */
+#submit-img, #submit-txt {
+  background: var(--accent) !important;
+  color: #1A0E05 !important;
+  border: none !important;
+  font-weight:700 !important;
+  letter-spacing:.04em !important;
+  font-family:'Space Grotesk', sans-serif !important;
+  box-shadow: 0 0 0 1px rgba(255,138,61,.0), 0 6px 18px -8px var(--accent) !important;
+  transition: transform .12s ease, box-shadow .12s ease !important;
+}
+#submit-img:hover, #submit-txt:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 10px 24px -8px var(--accent) !important;
+}
+#submit-img:active, #submit-txt:active { transform: translateY(0); }
+
+/* ── Description output ───────────────────────────────────────────────── */
+#desc-output textarea {
+  font-family:'Inter', sans-serif !important;
+  font-size:.88rem !important; line-height:1.6 !important;
+  color:var(--text) !important;
+  background:var(--surface) !important;
+}
+
+/* ── Run-locally panel ─────────────────────────────────────────────────── */
+#run-locally {
+  border:1px dashed var(--raised) !important;
+  background: transparent !important;
+}
+#run-locally code {
+  font-family:'JetBrains Mono', monospace !important;
+  font-size:.78rem !important;
+  background:var(--bg) !important;
+  border:1px solid var(--raised) !important;
+  border-radius:6px !important;
+  color:var(--accent) !important;
+}
+#run-locally pre {
+  background:var(--bg) !important;
+  border:1px solid var(--raised) !important;
+  border-radius:8px !important;
+  padding:10px 14px !important;
+}
+
+/* ── Tabs ──────────────────────────────────────────────────────────────── */
+.tab-nav button {
+  font-family:'Space Grotesk', sans-serif !important;
+  font-weight:600 !important; letter-spacing:.02em !important;
+  color: var(--text-dim) !important;
+}
+.tab-nav button.selected {
+  color: var(--accent) !important;
+}
+
+/* ── Misc ──────────────────────────────────────────────────────────────── */
+footer { display:none !important; }
+.gr-accordion { border-color: var(--raised) !important; }
+"""
+
+LOCAL_RUN_MD = """
+**Run this studio on your own machine** — no install beyond Python.
+
+```bash
+pip install gradio openai pillow
+python app_single.py
+```
+
+Then open **http://localhost:7860**
+
+By default the app uses a shared public API key (rate-limited). To use your
+own [modelbest.cn](https://modelbest.cn) key without typing it every time,
+set an environment variable before launching:
+
+```bash
+# macOS / Linux
+export MINICPM_API_KEY="sk-your-key-here"
+
+# Windows (PowerShell)
+$env:MINICPM_API_KEY="sk-your-key-here"
+```
+
+The app checks `MINICPM_API_KEY` first, then the **API Key** field below,
+then falls back to the shared public key.
+"""
+
+with gr.Blocks(title="Emberglade · MiniCPM-V 4.6", theme=gr.themes.Soft(), css=CSS) as demo:
+
+    gr.HTML(
+        """<div id="studio-header">
+          <div class="eyebrow"><span class="line"></span>MINICPM-V 4.6 · LIVE CHOREOGRAPHY<span class="line"></span></div>
+          <h1>Emberglade</h1>
+          <p>Upload an image. The model reads its mood — then choreographs every move, live.</p>
+        </div>"""
+    )
+
+    with gr.Tabs():
+        # ── Tab 1: Image pipeline ─────────────────────────────────────────────
+        with gr.TabItem("📷  Image → Performance"):
+            with gr.Row():
+                with gr.Column(scale=1):
+                    image_input  = gr.Image(type="pil", label="Upload image", height=240)
+                    prompt_input = gr.Textbox(value=DEFAULT_PROMPT, label="Prompt", lines=2)
+                    model_sel    = gr.Radio(choices=list(MODELS.keys()),
+                                            value=list(MODELS.keys())[0], label="Model")
+                    with gr.Accordion("Generation settings", open=False):
+                        max_tok = gr.Slider(64, 2048, value=DEFAULT_MAX_TOKENS, step=64, label="Max tokens")
+                        temp    = gr.Slider(0.0, 1.5, value=DEFAULT_TEMPERATURE, step=0.05, label="Temperature")
+                    with gr.Accordion("API key", open=False):
+                        api_key = gr.Textbox(label="Your key (optional)", type="password",
+                                             placeholder="sk-…  leave blank to use the shared key")
+                        gr.Markdown("Get your own at [modelbest.cn](https://modelbest.cn) — see **Run locally** below for setup.")
+                    img_btn = gr.Button("Start performance", variant="primary", elem_id="submit-img")
+                    gr.Examples(examples=PROMPT_EXAMPLES, inputs=[prompt_input], label="Prompt ideas")
+
+                with gr.Column(scale=1):
+                    cat_out  = gr.HTML(value=placeholder_html(), label="Stage")
+                    desc_out = gr.Textbox(label="Description (model output, streaming)", lines=7,
+                                          placeholder="The model's description will stream in here…",
+                                          elem_id="desc-output")
+
+            img_btn.click(
+                fn=run_image_pipeline,
+                inputs=[image_input, prompt_input, model_sel, max_tok, temp, api_key],
+                outputs=[desc_out, cat_out],
+            )
+            prompt_input.submit(
+                fn=run_image_pipeline,
+                inputs=[image_input, prompt_input, model_sel, max_tok, temp, api_key],
+                outputs=[desc_out, cat_out],
+            )
+
+        # ── Tab 2: Text-only (keyword dance, no API) ──────────────────────────
+        with gr.TabItem("✍️  Text → Performance"):
+            gr.Markdown("Type mood words for an instant performance — no API key needed.")
+            with gr.Row():
+                with gr.Column(scale=1):
+                    txt_input = gr.Textbox(
+                        label="Describe a mood",
+                        placeholder='"happy party" · "sad rain" · "energetic dance"',
+                        lines=3,
+                    )
+                    txt_btn = gr.Button("Start performance", variant="primary", elem_id="submit-txt")
+                    gr.Examples(
+                        examples=[["happy celebrate joy"],["sad lonely rain"],
+                                  ["energetic dance excited"],["calm peaceful"],
+                                  ["mysterious dark shadow"],["romantic love"],
+                                  ["tense nervous fear"],["nostalgic memory"],["angry rage"]],
+                        inputs=[txt_input], label="Quick examples",
+                    )
+                with gr.Column(scale=1):
+                    txt_cat = gr.HTML(value=placeholder_html(), label="Stage")
+
+            txt_btn.click(fn=generate_animation, inputs=[txt_input], outputs=[txt_cat])
+            txt_input.submit(fn=generate_animation, inputs=[txt_input], outputs=[txt_cat])
+
+    # ── Run locally ──────────────────────────────────────────────────────────
+    with gr.Accordion("⚙  Run locally", open=False, elem_id="run-locally"):
+        gr.Markdown(LOCAL_RUN_MD)
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860, show_error=True)

config/__init__.py

@@ -0,0 +1,21 @@
+from .settings import (
+    API_BASE_URL,
+    PUBLIC_API_KEY,
+    MODELS,
+    MODEL_PARAMS,
+    DEFAULT_PROMPT,
+    DEFAULT_MAX_TOKENS,
+    DEFAULT_TEMPERATURE,
+    IMAGE_QUALITY,
+)
+
+__all__ = [
+    "API_BASE_URL",
+    "PUBLIC_API_KEY",
+    "MODELS",
+    "MODEL_PARAMS",
+    "DEFAULT_PROMPT",
+    "DEFAULT_MAX_TOKENS",
+    "DEFAULT_TEMPERATURE",
+    "IMAGE_QUALITY",
+]

config/settings.py

@@ -0,0 +1,31 @@
+"""
+config/settings.py — all constants in one place.
+Change values here; nothing else needs editing.
+"""
+
+# ── API ───────────────────────────────────────────────────────────────────────
+API_BASE_URL   = "https://api.modelbest.cn/v1"
+
+# Free public key provided by OpenBMB — rate-limited, no signup.
+# Set env var MINICPM_API_KEY to override at runtime without touching code.
+PUBLIC_API_KEY = "sk-pQ8L2zF3XmR5kY9wV4jB7hN1tC6vM0xG3aD5sH2bJ9lK4cZ8"
+
+# ── Models ────────────────────────────────────────────────────────────────────
+# Both are 1.3 B parameters — well under the 32 B cap.
+MODELS: dict[str, str] = {
+    "⚡ Instruct  (fast, direct)":  "MiniCPM-V-4.6-Instruct",
+    "🧠 Thinking  (reasons first)": "MiniCPM-V-4.6-Thinking",
+}
+
+MODEL_PARAMS: dict[str, str] = {
+    "MiniCPM-V-4.6-Instruct": "1.3 B",
+    "MiniCPM-V-4.6-Thinking": "1.3 B",
+}
+
+# ── Generation defaults ───────────────────────────────────────────────────────
+DEFAULT_PROMPT      = "Describe this image in detail."
+DEFAULT_MAX_TOKENS  = 512
+DEFAULT_TEMPERATURE = 0.7
+
+# ── Image encoding ────────────────────────────────────────────────────────────
+IMAGE_QUALITY = 90          # JPEG quality sent to the API (0-100)

core/__init__.py

@@ -0,0 +1,4 @@
+from .api_client import stream_description
+from .image_utils import pil_to_data_url
+
+__all__ = ["stream_description", "pil_to_data_url"]

core/api_client.py

@@ -0,0 +1,102 @@
+"""
+core/api_client.py — MiniCPM-V API wrapper.
+
+Handles:
+  • OpenAI-compatible streaming via the `openai` SDK
+  • API key resolution (env var → UI field → public fallback)
+  • Friendly error messages for 401 / 429 / network failures
+"""
+
+import os
+from collections.abc import Generator
+
+from openai import OpenAI, APIStatusError, APIConnectionError
+from PIL import Image
+
+from config import API_BASE_URL, PUBLIC_API_KEY, MODELS
+from core.image_utils import pil_to_data_url
+
+
+def _resolve_key(ui_key: str) -> str:
+    """
+    Priority: env var MINICPM_API_KEY → UI field → hardcoded public key.
+    """
+    return (
+        os.environ.get("MINICPM_API_KEY", "").strip()
+        or (ui_key or "").strip()
+        or PUBLIC_API_KEY
+    )
+
+
+def stream_description(
+    image: Image.Image,
+    prompt: str,
+    model_label: str,
+    max_tokens: int,
+    temperature: float,
+    api_key: str,
+) -> Generator[str, None, None]:
+    """
+    Stream the model's response token-by-token.
+
+    Yields:
+        Cumulative response string — each yield is the full text so far,
+        so Gradio can update the textbox incrementally.
+    """
+    if image is None:
+        yield "⚠️  Please upload an image first."
+        return
+
+    key      = _resolve_key(api_key)
+    model_id = MODELS[model_label]
+    data_url = pil_to_data_url(image)
+
+    client = OpenAI(api_key=key, base_url=API_BASE_URL)
+
+    try:
+        stream = client.chat.completions.create(
+            model=model_id,
+            messages=[{
+                "role": "user",
+                "content": [
+                    {"type": "image_url", "image_url": {"url": data_url}},
+                    {"type": "text",      "text": prompt},
+                ],
+            }],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        )
+
+        result = ""
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content or ""
+            if delta:
+                result += delta
+                yield result
+
+    except APIStatusError as e:
+        if e.status_code == 401:
+            yield (
+                "🔐 **API key rejected (401).**\n\n"
+                "The public key may have hit its rate limit.  \n"
+                "Get a free personal key at https://modelbest.cn and paste it "
+                "in the **API Key** field."
+            )
+        elif e.status_code == 429:
+            yield (
+                "⏳ **Rate limit reached (429).**\n\n"
+                "The free public key is shared — wait a moment and retry, "
+                "or use your own key from https://modelbest.cn"
+            )
+        else:
+            yield f"❌ API error {e.status_code}:\n\n```\n{e.message}\n```"
+
+    except APIConnectionError:
+        yield (
+            "❌ **Cannot reach the API** (`api.modelbest.cn`).  \n"
+            "Check your internet connection and try again."
+        )
+
+    except Exception as e:
+        yield f"❌ Unexpected error:\n\n```\n{e}\n```"

core/image_utils.py

@@ -0,0 +1,27 @@
+"""
+core/image_utils.py — image encoding helpers.
+"""
+
+import base64
+import io
+
+from PIL import Image
+
+from config import IMAGE_QUALITY
+
+
+def pil_to_data_url(image: Image.Image) -> str:
+    """
+    Convert a PIL image to a JPEG base64 data URL suitable for the API.
+
+    Args:
+        image: Any PIL Image (RGB, RGBA, P, …).
+
+    Returns:
+        String of the form  'data:image/jpeg;base64,<b64>'
+    """
+    image = image.convert("RGB")
+    buf = io.BytesIO()
+    image.save(buf, format="JPEG", quality=IMAGE_QUALITY)
+    b64 = base64.b64encode(buf.getvalue()).decode()
+    return f"data:image/jpeg;base64,{b64}"

main.py

@@ -0,0 +1,19 @@
+"""
+main.py — entry point
+Run with:  python main.py
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure the project root is on sys.path so `core`, `ui`, `config` are importable
+# regardless of where Python is invoked from.
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from ui.app import build_ui
+
+if __name__ == "__main__":
+    demo = build_ui()
+    demo.launch(server_name="0.0.0.0", server_port=7860, show_error=True)

ui/__init__.py

@@ -0,0 +1,3 @@
+from .app import build_ui
+
+__all__ = ["build_ui"]

ui/app.py

@@ -0,0 +1,80 @@
+"""
+ui/app.py — Gradio layout.
+
+This file is pure layout — no inference logic lives here.
+All intelligence is in core/api_client.py.
+"""
+
+import gradio as gr
+
+from core import stream_description
+from ui.components import (
+    image_upload,
+    prompt_box,
+    model_selector,
+    generation_settings,
+    api_key_field,
+    prompt_examples,
+    output_box,
+    info_panel,
+)
+
+CSS = """
+#title        { text-align: center; }
+#submit       { background: #6366f1; color: white; }
+#submit:hover { background: #4f46e5; }
+#model-hint   { font-size: 0.85em; opacity: 0.75; }
+footer        { display: none !important; }
+"""
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(
+        title="MiniCPM-V · API Image Describer",
+        theme=gr.themes.Soft(),
+        css=CSS,
+    ) as demo:
+
+        gr.Markdown(
+            "# 🔍 MiniCPM-V 4.6 · Image Description via API\n"
+            "**No downloads. No GPU needed.** Calls OpenBMB's hosted API — "
+            "results stream back in real time.\n\n"
+            "> Models: `MiniCPM-V-4.6-Instruct` & `MiniCPM-V-4.6-Thinking` · "
+            "1.3 B params each · well under the 32 B cap · Apache-2.0",
+            elem_id="title",
+        )
+
+        with gr.Row():
+            # ── Left column — inputs ──────────────────────────────────────────
+            with gr.Column(scale=1):
+                image   = image_upload()
+                prompt  = prompt_box()
+                model   = model_selector()
+
+                gr.Markdown(
+                    "**Instruct** — direct, concise answer.  \n"
+                    "**Thinking** — reasons step-by-step first (slower, more thorough).",
+                    elem_id="model-hint",
+                )
+
+                max_tokens, temperature = generation_settings()
+                api_key = api_key_field()
+
+                submit = gr.Button(
+                    "▶ Describe Image", variant="primary", elem_id="submit"
+                )
+                prompt_examples(prompt)
+
+            # ── Right column — output ─────────────────────────────────────────
+            with gr.Column(scale=1):
+                output = output_box()
+                info_panel()
+
+        # ── Event wiring ──────────────────────────────────────────────────────
+        inputs  = [image, prompt, model, max_tokens, temperature, api_key]
+        outputs = [output]
+
+        submit.click(fn=stream_description, inputs=inputs, outputs=outputs)
+        prompt.submit(fn=stream_description, inputs=inputs, outputs=outputs)
+
+    return demo

ui/components.py

@@ -0,0 +1,103 @@
+"""
+ui/components.py — reusable Gradio input widgets.
+
+Each function returns (component, …) tuples so app.py stays declarative.
+"""
+
+import gradio as gr
+
+from config import (
+    MODELS,
+    DEFAULT_PROMPT,
+    DEFAULT_MAX_TOKENS,
+    DEFAULT_TEMPERATURE,
+)
+
+PROMPT_EXAMPLES = [
+    ["Describe this image in detail."],
+    ["List every object you can see."],
+    ["What is the mood or atmosphere of this image?"],
+    ["What text, if any, appears in this image?"],
+    ["Explain this image to someone who cannot see it."],
+    ["What is unusual or interesting about this image?"],
+]
+
+
+def image_upload() -> gr.Image:
+    return gr.Image(type="pil", label="📷 Input Image", height=320)
+
+
+def prompt_box() -> gr.Textbox:
+    return gr.Textbox(
+        value=DEFAULT_PROMPT,
+        label="💬 Prompt",
+        lines=3,
+        placeholder="Ask anything about the image…",
+    )
+
+
+def model_selector() -> gr.Radio:
+    return gr.Radio(
+        choices=list(MODELS.keys()),
+        value=list(MODELS.keys())[0],
+        label="🤖 Model",
+    )
+
+
+def generation_settings() -> tuple[gr.Slider, gr.Slider]:
+    """Returns (max_tokens_slider, temperature_slider)."""
+    with gr.Accordion("⚙️ Generation settings", open=False):
+        max_tokens = gr.Slider(
+            64, 2048, value=DEFAULT_MAX_TOKENS, step=64, label="Max tokens"
+        )
+        temperature = gr.Slider(
+            0.0, 1.5, value=DEFAULT_TEMPERATURE, step=0.05, label="Temperature"
+        )
+    return max_tokens, temperature
+
+
+def api_key_field() -> gr.Textbox:
+    with gr.Accordion("🔑 API Key", open=False):
+        box = gr.Textbox(
+            label="Your API key (optional)",
+            type="password",
+            lines=1,
+            placeholder="sk-…  leave blank to use the free public key",
+        )
+        gr.Markdown(
+            "A **free public key** is used when this field is blank.  \n"
+            "It is shared and rate-limited — paste your own key from "
+            "[modelbest.cn](https://modelbest.cn) for unlimited use."
+        )
+    return box
+
+
+def prompt_examples(prompt_input: gr.Textbox) -> gr.Examples:
+    return gr.Examples(
+        examples=PROMPT_EXAMPLES,
+        inputs=[prompt_input],
+        label="📝 Examples",
+    )
+
+
+def output_box() -> gr.Textbox:
+    return gr.Textbox(
+        label="📄 Model Description (streaming)",
+        lines=22,
+        placeholder="Response streams here token-by-token…",
+    )
+
+
+def info_panel() -> None:
+    gr.Markdown(
+        "---\n"
+        "**API details**\n"
+        "- Endpoint: `https://api.modelbest.cn/v1/chat/completions`\n"
+        "- Protocol: OpenAI-compatible (SSE streaming)\n"
+        "- Auth: Bearer token\n\n"
+        "**Models**\n"
+        "| Model | Params | Best for |\n"
+        "|---|---|---|\n"
+        "| Instruct | 1.3 B | Fast Q&A, descriptions |\n"
+        "| Thinking | 1.3 B | Complex reasoning, OCR |\n"
+    )