Upload folder using huggingface_hub

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,35 @@
+[
+  "tests/test_interpretation.py::test_extracts_json_object_from_surrounding_prose",
+  "tests/test_interpretation.py::test_includes_poem_and_correction",
+  "tests/test_interpretation.py::test_omits_correction_line_when_none_given",
+  "tests/test_interpretation.py::test_parses_guaranteed_json_into_both_fields",
+  "tests/test_interpretation.py::test_raises_clear_error_on_malformed_json",
+  "tests/test_interpretation.py::test_raises_when_fields_missing",
+  "tests/test_interpretation.py::test_strips_markdown_code_fences",
+  "tests/test_motion_and_registry.py::test_explicit_mode_wins",
+  "tests/test_motion_and_registry.py::test_motion_prompt_keeps_brief_and_adds_motion_clause",
+  "tests/test_motion_and_registry.py::test_resolve_mode_defaults_to_api_off_space",
+  "tests/test_motion_and_registry.py::test_resolve_mode_defaults_to_local_on_zerogpu",
+  "tests/test_song.py::test_every_style_has_tags_and_default_is_valid",
+  "tests/test_song.py::test_lyrics_handle_blank_and_whitespace_input_lines",
+  "tests/test_song.py::test_lyrics_keep_every_poem_line",
+  "tests/test_song.py::test_lyrics_split_single_line_poem_on_chinese_punctuation",
+  "tests/test_song.py::test_lyrics_use_structure_tags",
+  "tests/test_song.py::test_recognizes_only_supported_song_styles",
+  "tests/test_song.py::test_song_tags_falls_back_to_default_for_unknown_style",
+  "tests/test_styles.py::test_appends_curated_style_clause",
+  "tests/test_styles.py::test_defaults_to_watercolor",
+  "tests/test_styles.py::test_realistic_style_overrides_chinese_painting_wording",
+  "tests/test_styles.py::test_recognizes_only_supported_style_ids",
+  "tests/test_styles.py::test_removes_conflicting_art_direction_words_from_realistic_prompts",
+  "tests/test_textfree.py::test_appends_canonical_no_text_rule_when_brief_omits_it",
+  "tests/test_textfree.py::test_appends_full_bleed_rule_when_brief_omits_it",
+  "tests/test_textfree.py::test_does_not_duplicate_full_bleed_rule",
+  "tests/test_textfree.py::test_does_not_duplicate_text_free_rule",
+  "tests/test_textfree.py::test_exports_exact_safety_rule_strings",
+  "tests/test_textfree.py::test_keeps_original_brief_intact",
+  "tests/test_video_and_card.py::test_compose_card_returns_same_size_image_and_does_not_mutate_input",
+  "tests/test_video_and_card.py::test_mux_cmd_loops_video_under_full_song",
+  "tests/test_video_and_card.py::test_vertical_columns_descend_within_a_column",
+  "tests/test_video_and_card.py::test_vertical_columns_run_right_to_left"
+]

README.md

@@ -1,13 +1,86 @@
 ---
-title: Shi Cheng Hua
-emoji: 🚀
-colorFrom: blue
-colorTo: gray
+title: 诗成画 · Poem to Painting & Song
+emoji: 🖌️
+colorFrom: red
+colorTo: yellow
 sdk: gradio
 sdk_version: 6.17.3
-python_version: '3.13'
 app_file: app.py
-pinned: false
+python_version: "3.12"
+license: apache-2.0
+tags:
+  - build-small-hackathon
+  - track:thousand-token-wood
+  - an-adventure-in-thousand-token-wood
+  - achievement:offbrand
+  - off-brand
+  - achievement:bestdemo
+  - best-demo
+  - sponsor:openbmb
+  - minicpm
+  - flux2-klein
+  - ace-step
+  - wan2-2
+  - zerogpu
+  - text-to-image
+  - text-to-audio
+  - image-to-video
+short_description: 写一首诗，化作画、歌与会动的画卡 — all small open models
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 诗成画 · A poem becomes a painting, a song, and a living card
+
+Write (or speak) a short Chinese poem. The app **reads it back to you warmly**,
+**paints it** in your chosen classical style, **sings it** as a song, and finally
+**brings the painting to life** as a short video with your poem sung over it —
+a morning card you can send to family.
+
+Built for elders first: warm jargon-free Simplified Chinese, one big button per
+step, and a "一气呵成" button that does the whole journey in one go.
+
+## How it works — four small open models, all under 32B
+
+| Step | 中文 | Model | Size |
+|------|------|-------|------|
+| Read the poem | 读诗 | [openbmb/MiniCPM4.1-8B](https://huggingface.co/openbmb/MiniCPM4.1-8B) | 8B |
+| Paint it | 作画 | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | 4B |
+| Sing it | 唱诗 | [ACE-Step/Ace-Step1.5](https://huggingface.co/ACE-Step/Ace-Step1.5) | ~3.5B |
+| Bring it alive | 入画 | [Wan-AI/Wan2.2-TI2V-5B-Diffusers](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B-Diffusers) | 5B |
+
+The generated painting is always **text-free** (a hard rule injected into every
+brief); the poem calligraphy, greeting, and red seal are composed on top by the
+app, in classical vertical right-to-left layout. The song uses the poem itself
+as lyrics — verse from the full poem, the opening couplet repeated as chorus.
+The final video loops the animated painting under the full song.
+
+## Swappable providers
+
+Every capability sits behind a provider seam (`poetic/providers/`):
+
+- `local` — the models above, on ZeroGPU (this Space's default).
+- `api` — HF Inference Providers / Spaces (Qwen3-8B, FLUX.2 Klein via fal,
+  the official ACE-Step Space, Wan2.2 text-to-video), for dev boxes and CPU
+  fallback.
+
+Mode is `POETIC_MODE` (`local`/`api`); each capability can be overridden
+individually via `INTERPRET_PROVIDER` / `PAINT_PROVIDER` / `SING_PROVIDER` /
+`ANIMATE_PROVIDER`, and models via env (`INTERPRET_MODEL`, `PAINT_MODEL`, …).
+Swapping a model is a config change, not a code change.
+
+## Run it elsewhere
+
+```bash
+pip install -r requirements.txt gradio
+POETIC_MODE=api HF_TOKEN=hf_... python app.py
+```
+
+Pure logic is tested: `pytest tests/` (interpretation parsing/repair, style
+clauses, text-free guards, lyric formatting, card layout, video mux).
+
+## Links
+
+- Demo video: _(coming with submission)_
+- Social post: _(coming with submission)_
+
+— Built from the [poetic](https://github.com/) project's poem-to-art flow,
+re-imagined on small open models for Build Small.

app.py

@@ -0,0 +1,223 @@
+"""诗成画 — write a poem, watch it become a painting, a song, and a living card.
+
+Build Small hackathon Space. All models open-weight and under 32B parameters;
+see poetic/providers/ for the swappable provider seam (local ZeroGPU vs HF API).
+"""
+
+import gradio as gr
+
+from poetic import providers
+from poetic.card import compose_card
+from poetic.song import DEFAULT_SONG_STYLE, build_song_lyrics, song_tags
+from poetic.styles import DEFAULT_IMAGE_STYLE, apply_image_style
+from poetic.textfree import ensure_text_free
+from poetic.video import mux_song_into_video
+
+if providers.resolve_mode() == "local":
+    # ZeroGPU requires eager module-scope model loading; this import does it.
+    from poetic.providers import local_zerogpu  # noqa: F401
+
+IMAGE_STYLE_CHOICES = [
+    ("水墨留白", "inkWash"),
+    ("工笔淡彩", "gongbi"),
+    ("温柔水彩", "watercolor"),
+    ("海报色彩", "posterColor"),
+    ("写实", "realistic"),
+]
+
+SONG_STYLE_CHOICES = [
+    ("古风", "guofeng"),
+    ("民谣", "folk"),
+    ("摇篮曲", "lullaby"),
+    ("戏腔", "operatic"),
+    ("晨光", "uplifting"),
+]
+
+
+def do_interpret(poem: str, correction: str):
+    if not poem or not poem.strip():
+        raise gr.Error("请先写下您的诗，再请我来读。")
+    try:
+        interp = providers.get_interpreter().interpret(
+            poem.strip(), correction.strip() or None if correction else None
+        )
+    except ValueError as exc:
+        raise gr.Error(f"这一次没有读懂，请再试一下。({exc})") from exc
+    return f"### 画中之意\n\n{interp.understanding_zh}", interp.brief_en
+
+
+def do_paint(brief_en: str, style_id: str, poem: str, greeting: str):
+    if not brief_en:
+        raise gr.Error("请先点「读诗」，让我先体会诗意。")
+    brief = ensure_text_free(apply_image_style(brief_en, style_id or DEFAULT_IMAGE_STYLE))
+    painting = providers.get_painter().paint(brief)
+    card = compose_card(painting, poem, greeting or "")
+    return card, painting
+
+
+def do_sing(poem: str, song_style: str, duration: float):
+    if not poem or not poem.strip():
+        raise gr.Error("请先写下您的诗。")
+    lyrics = build_song_lyrics(poem.strip())
+    if not lyrics:
+        raise gr.Error("这首诗太短了，再写一两句吧。")
+    return providers.get_singer().sing(
+        song_tags(song_style or DEFAULT_SONG_STYLE), lyrics, float(duration)
+    )
+
+
+def do_animate(painting, brief_en: str, audio_path: str | None):
+    if painting is None:
+        raise gr.Error("请先点「作画」，有了画才能让它动起来。")
+    video = providers.get_animator().animate(painting, brief_en or "")
+    if audio_path:
+        video = mux_song_into_video(video, audio_path)
+    return video
+
+
+def do_everything(poem: str, greeting: str, style_id: str, song_style: str, duration: float):
+    understanding, brief_en = do_interpret(poem, "")
+    yield understanding, brief_en, gr.update(), gr.update(), gr.update(), gr.update()
+    card, painting = do_paint(brief_en, style_id, poem, greeting)
+    yield understanding, brief_en, card, painting, gr.update(), gr.update()
+    audio = do_sing(poem, song_style, duration)
+    yield understanding, brief_en, card, painting, audio, gr.update()
+    video = do_animate(painting, brief_en, audio)
+    yield understanding, brief_en, card, painting, audio, video
+
+
+CSS = """
+:root { --ink: #2b2620; --vermilion: #a63a2b; --paper: #f6f1e5; --paper-deep: #efe7d4; }
+.gradio-container {
+  background:
+    radial-gradient(1200px 500px at 80% -10%, #fbf7ec 0%, transparent 60%),
+    radial-gradient(900px 400px at -10% 110%, #f1e8d2 0%, transparent 55%),
+    var(--paper) !important;
+  font-family: "Noto Serif SC", "Source Han Serif SC", "Songti SC", serif !important;
+  color: var(--ink);
+}
+#title-block h1 {
+  font-size: 2.6rem; letter-spacing: 0.35rem; color: var(--ink);
+  border-bottom: 1px solid #d8cdb4; padding-bottom: 0.6rem;
+}
+#title-block .seal {
+  display: inline-block; background: var(--vermilion); color: #faf5eb;
+  padding: 0.1rem 0.45rem; border-radius: 4px; margin-left: 0.6rem;
+  font-size: 1.4rem; vertical-align: middle;
+}
+.step-card {
+  background: rgba(255, 252, 244, 0.82) !important;
+  border: 1px solid #ddd2b8 !important; border-radius: 14px !important;
+  box-shadow: 0 2px 14px rgba(90, 70, 40, 0.08) !important;
+  padding: 1rem !important; margin-top: 1rem !important;
+}
+.step-card .label-wrap span, .step-card label span { font-size: 1.05rem !important; }
+button.primary, .primary {
+  background: var(--vermilion) !important; border: none !important;
+  font-size: 1.15rem !important; letter-spacing: 0.2rem;
+}
+button.primary:hover { filter: brightness(1.08); }
+textarea, input[type="text"] { font-size: 1.15rem !important; line-height: 1.8 !important; }
+.step-number {
+  color: var(--vermilion); font-size: 1.2rem; letter-spacing: 0.2rem; margin-bottom: 0;
+}
+footer { display: none !important; }
+"""
+
+with gr.Blocks(title="诗成画 · Poem to Painting & Song") as demo:
+    with gr.Column(elem_id="title-block"):
+        gr.HTML(
+            "<h1>诗成画 <span class='seal'>印</span></h1>"
+            "<p style='font-size:1.1rem'>写一首小诗，我来替您读懂它、画出来、唱给您听，再让画活起来。"
+            "每一步用的都是开源小模型。</p>"
+        )
+
+    brief_state = gr.State("")
+    painting_state = gr.State(None)
+
+    with gr.Group(elem_classes="step-card"):
+        gr.Markdown("**一 · 写诗**", elem_classes="step-number")
+        poem_box = gr.Textbox(
+            label="您的诗", lines=4, placeholder="把您想说的写成几句小诗，长短都可以。"
+        )
+        greeting_box = gr.Textbox(
+            label="想送的问候（可以不填）", placeholder="例如：早安，或一句祝福的话"
+        )
+        with gr.Row():
+            interpret_btn = gr.Button("读诗", variant="primary")
+            everything_btn = gr.Button("一气呵成（读诗·作画·唱诗·入画）")
+
+    with gr.Group(elem_classes="step-card"):
+        gr.Markdown("**二 · 画中之意**", elem_classes="step-number")
+        understanding_md = gr.Markdown("点「读诗」后，我会把读到的画面说给您听。")
+        correction_box = gr.Textbox(
+            label="如果我没读对，请告诉我", placeholder="例如：我想要更温暖的颜色"
+        )
+        reinterpret_btn = gr.Button("按更正再读一次")
+        with gr.Accordion("给画师的英文说明（看看也无妨）", open=False):
+            brief_md = gr.Markdown("")
+
+    with gr.Group(elem_classes="step-card"):
+        gr.Markdown("**三 · 作画**", elem_classes="step-number")
+        style_radio = gr.Radio(
+            IMAGE_STYLE_CHOICES, value=DEFAULT_IMAGE_STYLE, label="选一种画风"
+        )
+        paint_btn = gr.Button("作画", variant="primary")
+        card_image = gr.Image(label="您的画卡", type="pil", interactive=False)
+
+    with gr.Group(elem_classes="step-card"):
+        gr.Markdown("**四 · 唱诗**", elem_classes="step-number")
+        with gr.Row():
+            song_radio = gr.Radio(
+                SONG_STYLE_CHOICES, value=DEFAULT_SONG_STYLE, label="选一种曲风"
+            )
+            duration_slider = gr.Slider(20, 60, value=40, step=5, label="歌曲长度（秒）")
+        sing_btn = gr.Button("唱诗", variant="primary")
+        song_audio = gr.Audio(label="您的诗，唱出来了", type="filepath", interactive=False)
+
+    with gr.Group(elem_classes="step-card"):
+        gr.Markdown("**五 · 入画**", elem_classes="step-number")
+        gr.Markdown("让画轻轻动起来，配上您的歌，做成一段可以发给家人的小影片。")
+        animate_btn = gr.Button("让画活起来", variant="primary")
+        video_out = gr.Video(label="会唱歌的画", interactive=False)
+
+    gr.Examples(
+        examples=[
+            ["床前明月光，疑是地上霜。举头望明月，低头思故乡。", "晚安"],
+            ["白日依山尽，黄河入海流。欲穷千里目，更上一层楼。", "早安"],
+            ["春眠不觉晓，处处闻啼鸟。夜来风雨声，花落知多少。", ""],
+        ],
+        inputs=[poem_box, greeting_box],
+        label="试试这些诗（也欢迎写您自己的）",
+        cache_examples=False,
+    )
+
+    interpret_btn.click(
+        do_interpret, inputs=[poem_box, correction_box], outputs=[understanding_md, brief_state]
+    ).then(lambda b: b, inputs=brief_state, outputs=brief_md)
+    reinterpret_btn.click(
+        do_interpret, inputs=[poem_box, correction_box], outputs=[understanding_md, brief_state]
+    ).then(lambda b: b, inputs=brief_state, outputs=brief_md)
+
+    paint_btn.click(
+        do_paint,
+        inputs=[brief_state, style_radio, poem_box, greeting_box],
+        outputs=[card_image, painting_state],
+    )
+
+    sing_btn.click(
+        do_sing, inputs=[poem_box, song_radio, duration_slider], outputs=song_audio
+    )
+
+    animate_btn.click(
+        do_animate, inputs=[painting_state, brief_state, song_audio], outputs=video_out
+    )
+
+    everything_btn.click(
+        do_everything,
+        inputs=[poem_box, greeting_box, style_radio, song_radio, duration_slider],
+        outputs=[understanding_md, brief_state, card_image, painting_state, song_audio, video_out],
+    )
+
+if __name__ == "__main__":
+    demo.launch(css=CSS)

conftest.py

@@ -0,0 +1 @@
+# Makes `import poetic` work when running pytest from the space/ directory.

poetic/card.py

@@ -0,0 +1,82 @@
+"""Compose the final card: poem calligraphy + greeting + seal over the painting.
+
+Mirrors the Expo app's react-native-svg overlay — the painting itself stays
+text-free (TEXT_FREE_RULE); all characters are drawn here, on top.
+Classical layout: vertical columns read right-to-left, seal at bottom-left.
+"""
+
+import os
+import urllib.request
+
+from PIL import Image, ImageDraw, ImageFont
+
+from poetic.song import split_poem_lines
+
+_FONT_URL = (
+    "https://github.com/notofonts/noto-cjk/raw/main/Serif/SubsetOTF/SC/NotoSerifSC-Regular.otf"
+)
+_FONT_CACHE = os.path.join(os.path.expanduser("~"), ".cache", "poetic", "NotoSerifSC-Regular.otf")
+
+
+def _load_font(size: int):
+    try:
+        if not os.path.exists(_FONT_CACHE):
+            os.makedirs(os.path.dirname(_FONT_CACHE), exist_ok=True)
+            urllib.request.urlretrieve(_FONT_URL, _FONT_CACHE)
+        return ImageFont.truetype(_FONT_CACHE, size)
+    except Exception:
+        # Offline or font host unreachable: degrade to the default font rather
+        # than failing the whole card.
+        return ImageFont.load_default(size)
+
+
+def layout_vertical_columns(
+    lines: list[str], char_size: int, gap: int, top: int, right: int
+) -> list[tuple[str, int, int]]:
+    """Place poem characters in vertical columns, right-to-left.
+
+    Returns (char, x, y) tuples. Pure geometry — unit-testable without PIL.
+    """
+    placements: list[tuple[str, int, int]] = []
+    column_pitch = char_size + gap
+    for col, line in enumerate(lines):
+        x = right - (col + 1) * column_pitch
+        for row, char in enumerate(line):
+            placements.append((char, x, top + row * (char_size + gap // 2)))
+    return placements
+
+
+def compose_card(
+    painting: Image.Image,
+    poem: str,
+    greeting: str = "",
+    seal_text: str = "诗",
+) -> Image.Image:
+    card = painting.convert("RGB").copy()
+    draw = ImageDraw.Draw(card)
+    w, h = card.size
+
+    char_size = max(18, w // 18)
+    font = _load_font(char_size)
+    lines = split_poem_lines(poem)[:4]
+
+    for char, x, y in layout_vertical_columns(
+        lines, char_size, gap=char_size // 3, top=h // 12, right=w - w // 16
+    ):
+        draw.text((x + 1, y + 2), char, font=font, fill=(40, 30, 20, 160))
+        draw.text((x, y), char, font=font, fill=(35, 30, 28))
+
+    if greeting:
+        greeting_size = max(24, w // 10)
+        greeting_font = _load_font(greeting_size)
+        gx, gy = w // 14, h - h // 5
+        draw.text((gx + 2, gy + 2), greeting, font=greeting_font, fill=(40, 30, 20, 160))
+        draw.text((gx, gy), greeting, font=greeting_font, fill=(120, 30, 25))
+
+    seal = max(20, w // 16)
+    sx, sy = w // 14, h - h // 12 - seal
+    draw.rectangle([sx, sy, sx + seal, sy + seal], fill=(178, 34, 34))
+    seal_font = _load_font(int(seal * 0.72))
+    draw.text((sx + seal * 0.14, sy + seal * 0.08), seal_text[:1], font=seal_font, fill=(250, 245, 235))
+
+    return card

poetic/interpretation.py

@@ -0,0 +1,46 @@
+import json
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Interpretation:
+    understanding_zh: str
+    brief_en: str
+
+
+def build_interpret_contents(poem: str, correction: str | None = None) -> str:
+    base = f"诗：\n{poem}"
+    return f"{base}\n\n长者的更正：{correction}" if correction else base
+
+
+_FENCE_RE = re.compile(r"^```[a-zA-Z]*\s*|\s*```$", re.MULTILINE)
+
+
+def parse_interpretation(text: str) -> Interpretation:
+    """Parse the model's reply into both audience fields.
+
+    MiniCPM/Qwen have no enforced response schema (unlike Vertex AI), so this
+    repairs the two common wrappings before giving up: Markdown code fences and
+    prose surrounding the JSON object.
+    """
+    candidates = [text, _FENCE_RE.sub("", text).strip()]
+    start, end = text.find("{"), text.rfind("}")
+    if start != -1 and end > start:
+        candidates.append(text[start : end + 1])
+
+    obj = None
+    for candidate in candidates:
+        try:
+            obj = json.loads(candidate)
+            break
+        except (json.JSONDecodeError, ValueError):
+            continue
+    if obj is None:
+        raise ValueError(f"Failed to parse interpretation JSON: {text[:120]}")
+
+    understanding = obj.get("understandingZh") if isinstance(obj, dict) else None
+    brief = obj.get("briefEn") if isinstance(obj, dict) else None
+    if not isinstance(understanding, str) or not isinstance(brief, str):
+        raise ValueError("Interpretation missing required fields")
+    return Interpretation(understanding_zh=understanding, brief_en=brief)

poetic/motion.py

@@ -0,0 +1,13 @@
+# Stage 4 (入画 / animate): the painting must come alive without being repainted.
+# The motion clause asks for ambient, loopable movement and pins the composition
+# so the video reads as "the card breathing", not a new scene.
+MOTION_CLAUSE = (
+    "The painting gently comes alive: soft ambient motion only — mist drifting, water rippling,"
+    " petals or leaves swaying, light shimmering. Slow, dreamy, loop-friendly movement."
+    " Keep the exact composition, palette and subjects of the painting; no new objects,"
+    " no camera cuts, no text."
+)
+
+
+def build_motion_prompt(brief: str) -> str:
+    return f"{brief.strip()}\n\n{MOTION_CLAUSE}"

poetic/prompts.py

@@ -0,0 +1,19 @@
+# System instruction for Stage 1 (读诗 / interpret), ported verbatim from
+# src/lib/interpretPrompt.ts so the hackathon Space and the production app
+# read poems the same way. The model must return JSON: {understandingZh, briefEn}.
+INTERPRET_SYSTEM_PROMPT = """
+你是一位懂中国古典诗意和中国画构图的温和读诗人，正在帮助一位长者把他亲手写的中文诗变成一张早安画卡。
+
+请先体会诗的意境、情绪、季节、时间、光线和空间感，不要只机械地罗列诗中的物件。若诗意含蓄，请用山水、花鸟、留白等中国审美词汇表达其气韵，但不要把最终画风锁死；应用稍后会按用户选择改成水彩、工笔、写实等不同画风。除非诗中明确需要人物，否则避免画清晰人脸。
+
+若输入中包含"长者的更正"，请把它当作最重要的指示，据此重新调整你的理解与画面。
+
+你必须只返回 JSON，不要 Markdown 或解释文字。JSON 包含两个字段：
+understandingZh：用温暖、平实、尊重的简体中文，简短地（两三句话）向长者复述你读到的画面和意境，让他觉得"这首诗被懂了"。不要使用技术词。
+briefEn：写给图像模型的、流畅自然且具体的英文画面说明，描述场景、季节、时间、天气、构图、色调、主体关系和情绪。重点写清楚“画什么”和“怎样构图”，不要强行指定最终画风；可以把 shan-shui (山水)、liúbái (留白) 作为意境和构图词，但避免把所有 brief 都写成 ink-wash 或 classical Chinese painting。
+
+briefEn 必须明确要求背景图不要包含任何文字，因为诗和问候语会由应用稍后叠加。briefEn 必须原样写入这条英文硬性规则：
+a painting only — no text, no Chinese characters, no calligraphy, no seals, no watermark
+
+不要替用户写诗，不要添加新的问候语，不要把诗句放进画面里。
+""".strip()

poetic/providers/__init__.py

@@ -0,0 +1,50 @@
+"""Provider registry — one seam per capability so models swap by config, not code.
+
+Selection order per capability:
+1. Explicit env var (INTERPRET_PROVIDER / PAINT_PROVIDER / SING_PROVIDER / ANIMATE_PROVIDER)
+2. POETIC_MODE bundle ("local" = on-Space ZeroGPU pipelines, "api" = remote inference)
+3. Default mode: "local" when running on ZeroGPU, else "api".
+"""
+
+import os
+from functools import cache
+
+
+def resolve_mode() -> str:
+    mode = os.environ.get("POETIC_MODE")
+    if mode in ("local", "api"):
+        return mode
+    return "local" if os.environ.get("SPACES_ZERO_GPU") else "api"
+
+
+def _resolve(capability: str, env_var: str):
+    name = os.environ.get(env_var) or resolve_mode()
+    if name == "local":
+        from poetic.providers import local_zerogpu as module
+    elif name == "api":
+        from poetic.providers import hf_api as module
+    else:
+        raise ValueError(
+            f"Unknown {env_var}={name!r}; expected 'local' or 'api'"
+        )
+    return getattr(module, capability)()
+
+
+@cache
+def get_interpreter():
+    return _resolve("Interpreter", "INTERPRET_PROVIDER")
+
+
+@cache
+def get_painter():
+    return _resolve("Painter", "PAINT_PROVIDER")
+
+
+@cache
+def get_singer():
+    return _resolve("Singer", "SING_PROVIDER")
+
+
+@cache
+def get_animator():
+    return _resolve("Animator", "ANIMATE_PROVIDER")

poetic/providers/hf_api.py

@@ -0,0 +1,120 @@
+"""Remote providers via HF Inference Providers / Spaces — every model open-weight, <32B.
+
+This bundle works anywhere with an HF_TOKEN (dev boxes, CPU Spaces). The local
+ZeroGPU bundle (local_zerogpu.py) is the hackathon-submission path; this one is
+the swap target the rest of the app can fall back to without code changes.
+"""
+
+import os
+import tempfile
+
+from huggingface_hub import InferenceClient
+
+from poetic.interpretation import Interpretation, build_interpret_contents, parse_interpretation
+from poetic.prompts import INTERPRET_SYSTEM_PROMPT
+
+# MiniCPM is not on HF Inference Providers, so api-mode interpretation uses an
+# open zh-strong chat model; the Space's local mode uses MiniCPM itself.
+DEFAULT_INTERPRET_MODEL = "Qwen/Qwen3-8B"
+# The router exposes FLUX.2-klein only as image-to-image, so api mode paints
+# with Qwen-Image (20B, Apache-2.0); local mode uses FLUX.2-klein-4B directly.
+DEFAULT_PAINT_MODEL = "Qwen/Qwen-Image"
+DEFAULT_SING_SPACE = "ACE-Step/Ace-Step-v1.5"
+DEFAULT_ANIMATE_MODEL = "Wan-AI/Wan2.2-TI2V-5B"
+
+
+def _client(provider_env: str | None = None) -> InferenceClient:
+    # Routing provider (fal-ai, together, replicate, …) is chosen per capability
+    # (e.g. PAINT_HF_PROVIDER), falling back to HF_PROVIDER, then router "auto".
+    # Per-capability matters: each model is live on a different provider set.
+    provider = (provider_env and os.environ.get(provider_env)) or os.environ.get("HF_PROVIDER")
+    return InferenceClient(token=os.environ.get("HF_TOKEN"), provider=provider)
+
+
+class Interpreter:
+    def interpret(self, poem: str, correction: str | None = None) -> Interpretation:
+        model = os.environ.get("INTERPRET_MODEL", DEFAULT_INTERPRET_MODEL)
+        response = _client("INTERPRET_HF_PROVIDER").chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": INTERPRET_SYSTEM_PROMPT},
+                {"role": "user", "content": build_interpret_contents(poem, correction)},
+            ],
+            max_tokens=1024,
+        )
+        return parse_interpretation(response.choices[0].message.content)
+
+
+class Painter:
+    def paint(self, brief: str):
+        model = os.environ.get("PAINT_MODEL", DEFAULT_PAINT_MODEL)
+        return _client("PAINT_HF_PROVIDER").text_to_image(brief, model=model, width=768, height=1024)
+
+
+def _first_audio_path(result) -> str | None:
+    """Depth-first scan of a gradio_client result for the first audio file."""
+    if isinstance(result, str) and result.lower().endswith((".mp3", ".flac", ".wav")):
+        return result
+    if isinstance(result, dict):
+        for value in result.values():
+            if (found := _first_audio_path(value)) is not None:
+                return found
+    if isinstance(result, (list, tuple)):
+        for value in result:
+            if (found := _first_audio_path(value)) is not None:
+                return found
+    return None
+
+
+class Singer:
+    def sing(self, tags: str, lyrics: str, duration: float = 40.0) -> str:
+        """Generate a sung rendition through the official ACE-Step Space.
+
+        Dev/fallback path only — the hackathon Space runs ACEStepPipeline
+        locally. The wrapper endpoint exposes ~50 positional params; we set the
+        custom-mode essentials (caption=param_4, lyrics=param_5,
+        duration=param_15) and leave the rest at their defaults.
+        """
+        from gradio_client import Client
+
+        space = os.environ.get("SING_SPACE", DEFAULT_SING_SPACE)
+        client = Client(space, token=os.environ.get("HF_TOKEN"))
+        # The wrapper marks several params required while still publishing
+        # defaults; build the full kwargs from the live API info so this stays
+        # robust as the Space evolves, then override our four essentials.
+        endpoint = client.view_api(return_format="dict", print_info=False)[
+            "named_endpoints"
+        ]["/generation_wrapper"]
+        kwargs = {
+            p["parameter_name"]: p.get("parameter_default")
+            for p in endpoint["parameters"]
+            if p.get("parameter_name")
+        }
+        kwargs.update(
+            selected_model=os.environ.get("SING_SPACE_MODEL", "acestep-v15-turbo"),
+            generation_mode="custom",
+            param_4=tags,      # caption / style tags
+            param_5=lyrics,    # lyrics
+            param_15=float(duration),
+        )
+        result = client.predict(api_name="/generation_wrapper", **kwargs)
+        audio = _first_audio_path(result)
+        if audio is None:
+            raise RuntimeError(f"No audio file in ACE-Step Space response: {str(result)[:200]}")
+        return audio
+
+
+class Animator:
+    def animate(self, image, brief: str) -> str:
+        """API mode runs text-to-video (the HF router exposes Wan2.2 as t2v only),
+        so the painting image is used as mood reference via the brief, not as the
+        first frame. The local provider does true image-to-video."""
+        model = os.environ.get("ANIMATE_MODEL", DEFAULT_ANIMATE_MODEL)
+        video_bytes = _client("ANIMATE_HF_PROVIDER").text_to_video(
+            f"{brief}\n\nGentle, slow, dreamy camera drift; subtle natural motion only.",
+            model=model,
+        )
+        out = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+        out.write(video_bytes)
+        out.close()
+        return out.name

poetic/providers/local_zerogpu.py

@@ -0,0 +1,158 @@
+"""On-Space providers: every model open-weight and under 32B, running on ZeroGPU.
+
+interpret  openbmb/MiniCPM4.1-8B          (sponsor: OpenBMB)
+paint      black-forest-labs/FLUX.2-klein-4B  (sponsor: Black Forest Labs)
+sing       ACE-Step/Ace-Step1.5 (~3.5B)
+animate    Wan-AI/Wan2.2-TI2V-5B-Diffusers
+
+ZeroGPU rules applied here: models load eagerly at module scope with
+device="cuda" (the platform registers weights and streams them in per call);
+real CUDA work only happens inside @spaces.GPU functions; every declared
+duration is the realistic worst case, not the default 60s; outputs go to
+tempfiles; returns are picklable (PIL images, file paths).
+"""
+
+import os
+import tempfile
+
+import spaces
+import torch
+
+from poetic.interpretation import Interpretation, build_interpret_contents, parse_interpretation
+from poetic.motion import build_motion_prompt
+from poetic.prompts import INTERPRET_SYSTEM_PROMPT
+
+INTERPRET_MODEL_ID = os.environ.get("INTERPRET_LOCAL_MODEL", "openbmb/MiniCPM4.1-8B")
+PAINT_MODEL_ID = os.environ.get("PAINT_LOCAL_MODEL", "black-forest-labs/FLUX.2-klein-4B")
+ANIMATE_MODEL_ID = os.environ.get("ANIMATE_LOCAL_MODEL", "Wan-AI/Wan2.2-TI2V-5B-Diffusers")
+
+# Painting is 3:4 portrait, matching the production app's card format.
+PAINT_WIDTH, PAINT_HEIGHT = 768, 1024
+
+ANIMATE_STEPS = int(os.environ.get("ANIMATE_STEPS", "20"))
+ANIMATE_FRAMES = int(os.environ.get("ANIMATE_FRAMES", "49"))
+ANIMATE_FPS = 16
+
+_WAN_NEGATIVE_PROMPT = (
+    "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，"
+    "低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，"
+    "毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走"
+)
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# --- interpret: MiniCPM ----------------------------------------------------
+from transformers import AutoModelForCausalLM, AutoTokenizer  # noqa: E402
+
+_tokenizer = AutoTokenizer.from_pretrained(INTERPRET_MODEL_ID, trust_remote_code=True)
+_llm = AutoModelForCausalLM.from_pretrained(
+    INTERPRET_MODEL_ID, torch_dtype=torch.bfloat16, trust_remote_code=True
+).to(device)
+
+# --- paint: FLUX.2 Klein ----------------------------------------------------
+from diffusers import Flux2KleinPipeline  # noqa: E402
+
+_flux = Flux2KleinPipeline.from_pretrained(PAINT_MODEL_ID, torch_dtype=torch.bfloat16).to(device)
+
+# --- animate: Wan 2.2 TI2V-5B ----------------------------------------------
+from diffusers import WanImageToVideoPipeline  # noqa: E402
+from diffusers.utils import export_to_video  # noqa: E402
+
+_wan = WanImageToVideoPipeline.from_pretrained(
+    ANIMATE_MODEL_ID, torch_dtype=torch.bfloat16
+).to(device)
+
+# --- sing: ACE-Step ---------------------------------------------------------
+# ACEStepPipeline manages its own checkpoint download and device placement
+# lazily on first call (inside the GPU context); constructing it here is cheap.
+from acestep.pipeline_ace_step import ACEStepPipeline  # noqa: E402
+
+_acestep = ACEStepPipeline(dtype="bfloat16")
+
+
+@spaces.GPU(duration=45)
+def _interpret_gpu(poem: str, correction: str | None) -> str:
+    messages = [
+        {"role": "system", "content": INTERPRET_SYSTEM_PROMPT},
+        {"role": "user", "content": build_interpret_contents(poem, correction)},
+    ]
+    try:
+        prompt_text = _tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
+        )
+    except TypeError:  # chat template without an enable_thinking switch
+        prompt_text = _tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+    inputs = _tokenizer(prompt_text, return_tensors="pt").to(device)
+    output = _llm.generate(
+        **inputs, max_new_tokens=1024, do_sample=True, temperature=0.7, top_p=0.95
+    )
+    return _tokenizer.decode(output[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
+
+
+@spaces.GPU(duration=30)
+def _paint_gpu(brief: str):
+    return _flux(
+        brief,
+        num_inference_steps=4,
+        guidance_scale=1.0,
+        width=PAINT_WIDTH,
+        height=PAINT_HEIGHT,
+    ).images[0]
+
+
+@spaces.GPU(duration=90)
+def _sing_gpu(tags: str, lyrics: str, duration: float) -> str:
+    out = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+    out.close()
+    _acestep(
+        prompt=tags,
+        lyrics=lyrics,
+        audio_duration=duration,
+        save_path=out.name,
+    )
+    return out.name
+
+
+def _estimate_animate_duration(image, brief: str) -> int:
+    # ~6s per denoising step at 768x1024x49f on a half-slice, plus model stream-in.
+    return min(540, 60 + ANIMATE_STEPS * 6 * max(1, ANIMATE_FRAMES // 49))
+
+
+@spaces.GPU(duration=_estimate_animate_duration)
+def _animate_gpu(image, brief: str) -> str:
+    frames = _wan(
+        image=image.convert("RGB").resize((PAINT_WIDTH, PAINT_HEIGHT)),
+        prompt=build_motion_prompt(brief),
+        negative_prompt=_WAN_NEGATIVE_PROMPT,
+        width=PAINT_WIDTH,
+        height=PAINT_HEIGHT,
+        num_frames=ANIMATE_FRAMES,
+        num_inference_steps=ANIMATE_STEPS,
+        guidance_scale=5.0,
+    ).frames[0]
+    out = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+    out.close()
+    export_to_video(frames, out.name, fps=ANIMATE_FPS)
+    return out.name
+
+
+class Interpreter:
+    def interpret(self, poem: str, correction: str | None = None) -> Interpretation:
+        return parse_interpretation(_interpret_gpu(poem, correction))
+
+
+class Painter:
+    def paint(self, brief: str):
+        return _paint_gpu(brief)
+
+
+class Singer:
+    def sing(self, tags: str, lyrics: str, duration: float = 40.0) -> str:
+        return _sing_gpu(tags, lyrics, duration)
+
+
+class Animator:
+    def animate(self, image, brief: str) -> str:
+        return _animate_gpu(image, brief)

poetic/song.py

@@ -0,0 +1,67 @@
+import re
+
+# Stage 3 (唱诗 / sing): turn the poem into ACE-Step inputs. ACE-Step takes a
+# comma-separated style/instrument/vocal tag prompt plus lyrics with [verse] /
+# [chorus] structure tags. Every preset must request vocals — the whole point
+# is the poem being sung, never an instrumental.
+
+SONG_STYLE_IDS = ("guofeng", "folk", "lullaby", "operatic", "uplifting")
+
+DEFAULT_SONG_STYLE = "guofeng"
+
+SONG_STYLE_TAGS = {
+    "guofeng": (
+        "chinese classical guofeng, guzheng, dizi flute, erhu strings, gentle female vocals,"
+        " elegant, serene, poetic ballad, mandarin singing"
+    ),
+    "folk": (
+        "acoustic folk ballad, fingerstyle guitar, warm male vocals, intimate, storytelling,"
+        " soft percussion, mandarin singing"
+    ),
+    "lullaby": (
+        "gentle lullaby, music box, soft humming female vocals, slow tempo, warm, soothing,"
+        " night song, mandarin singing"
+    ),
+    "operatic": (
+        "chinese opera influenced, jinghu, dramatic operatic female vocals, traditional percussion,"
+        " expressive xiqiang, mandarin singing"
+    ),
+    "uplifting": (
+        "uplifting pop ballad, piano, strings, bright female vocals, hopeful sunrise mood,"
+        " morning energy, mandarin singing"
+    ),
+}
+
+
+def is_song_style_id(value: object) -> bool:
+    return isinstance(value, str) and value in SONG_STYLE_IDS
+
+
+def song_tags(style_id: str) -> str:
+    return SONG_STYLE_TAGS.get(style_id, SONG_STYLE_TAGS[DEFAULT_SONG_STYLE])
+
+
+_LINE_SPLIT_RE = re.compile(r"[，。！？；、…,.;!?　]+")
+
+
+def split_poem_lines(poem: str) -> list[str]:
+    """Split a poem into lyric lines on newlines and Chinese/ASCII punctuation."""
+    lines: list[str] = []
+    for raw_line in poem.splitlines():
+        for piece in _LINE_SPLIT_RE.split(raw_line):
+            piece = piece.strip()
+            if piece:
+                lines.append(piece)
+    return lines
+
+
+def build_song_lyrics(poem: str) -> str:
+    """Format the poem as ACE-Step lyrics: the full poem as a verse, with the
+    opening couplet repeated as a chorus so the song has a memorable hook."""
+    lines = split_poem_lines(poem)
+    if not lines:
+        return ""
+
+    verse = "\n".join(lines)
+    chorus = "\n".join(lines[:2])
+    return f"[verse]\n{verse}\n\n[chorus]\n{chorus}"

poetic/styles.py

@@ -0,0 +1,117 @@
+import re
+
+# Ported from src/lib/imageStyle.ts — the five curated painting styles and the
+# realistic-style conflict scrubbing that keeps user style choice authoritative.
+
+IMAGE_STYLE_IDS = ("inkWash", "gongbi", "watercolor", "posterColor", "realistic")
+
+DEFAULT_IMAGE_STYLE = "watercolor"
+
+STYLE_CLAUSES = {
+    "inkWash": (
+        "Selected style / 已选画风: Ink wash / 水墨留白. Render the scene as classical Chinese"
+        " shui-mo ink-wash painting with shan-shui feeling, soft ink diffusion, restrained palette,"
+        " generous liúbái (留白), poetic mist, elegant brushwork."
+    ),
+    "gongbi": (
+        "Selected style / 已选画风: Gongbi / 工笔淡彩. Render the scene as refined gongbi-style"
+        " classical Chinese painting, delicate fine-line brushwork, light mineral colors, graceful"
+        " botanical and landscape details, calm scholarly elegance."
+    ),
+    "watercolor": (
+        "Selected style / 已选画风: Watercolor / 温柔水彩. Reinterpret the same poem mood as soft"
+        " transparent watercolor painting, gentle washes, wet-on-wet edges, airy light, warm handmade"
+        " paper texture, quiet morning-card mood. Conflicting ink-wash or gongbi wording in the scene"
+        " brief is only a mood reference."
+    ),
+    "posterColor": (
+        "Selected style / 已选画风: Poster color / 海报色彩. Reinterpret the same poem mood as vintage"
+        " poster-color and gouache painting, richer flat color fields, simplified elegant shapes, warm"
+        " auspicious palette, refined print-like composition. Conflicting ink-wash or gongbi wording in"
+        " the scene brief is only a mood reference."
+    ),
+    "realistic": (
+        "Selected style / 已选画风: Realistic / 写实. This selection is mandatory and overrides any"
+        " earlier Chinese-painting, shui-mo, gongbi, watercolor, shan-shui, scroll, antique paper,"
+        " ink-brush, or illustration style wording in the scene brief. Preserve only the poem's subject,"
+        " season, mood, and composition cues. Render a realistic, life-like scene from the real world"
+        " with natural sunlight, believable depth, true botanical forms, real textures and materials,"
+        " atmospheric perspective, and a subtle painterly finish. Avoid stylized Chinese painting, ink"
+        " wash, watercolor wash, flat poster shapes, calligraphy aesthetics, scroll-paper framing,"
+        " ornamental borders, and decorative seal motifs."
+    ),
+}
+
+_REALISTIC_CONFLICT_PATTERNS = [
+    re.compile(p, re.IGNORECASE)
+    for p in (
+        r"\bclassical Chinese (?:painting|art)\b",
+        r"\btraditional Chinese (?:painting|art)\b",
+        r"\bChinese (?:ink[- ]?wash|painting|brush|scroll)\b",
+        r"\bshan[- ]?shui\b",
+        r"\bshui[- ]?mo\b",
+        r"\bgongbi(?:-style)?\b",
+        r"\bink[- ]?wash(?: painting)?\b",
+        r"\bwatercolor(?: wash| painting)?\b",
+        r"\bposter[- ]?color\b",
+        r"\bgouache\b",
+        r"\bscroll[- ]?paper\b",
+        r"\bantique paper\b",
+        r"\bhandmade paper texture\b",
+        r"\bbrushwork\b",
+        r"\bcalligraphy aesthetics?\b",
+        r"\bornamental borders?\b",
+        r"\bdecorative seal motifs?\b",
+        r"\bclassical painting\b",
+    )
+] + [re.compile(r"水墨|山水|工笔|淡彩|留白|书法|印章|卷轴|宣纸|国画|古画")]
+
+
+def is_image_style_id(value: object) -> bool:
+    return isinstance(value, str) and value in IMAGE_STYLE_IDS
+
+
+def apply_image_style(brief: str, style_id: str = DEFAULT_IMAGE_STYLE) -> str:
+    clause = STYLE_CLAUSES.get(style_id, STYLE_CLAUSES[DEFAULT_IMAGE_STYLE])
+    clean_brief = _sanitize_brief_for_style(brief, style_id)
+
+    if style_id == "realistic":
+        return "\n\n".join(
+            [
+                clause,
+                "Real-world scene description extracted from the poem, with conflicting art-style words removed:",
+                clean_brief,
+                "Make it look like a believable real-world scene first, not an illustration or Chinese"
+                " painting. Keep the generated image text-free; the app adds poem text later.",
+            ]
+        )
+
+    return "\n\n".join(
+        [
+            "The user's selected visual style is authoritative and must control the final image. If the"
+            " scene brief below contains style words that conflict with the selected style, keep only the"
+            " poem meaning, subject, mood, and composition cues, then render in the selected style.",
+            f"Scene brief to reinterpret:\n{clean_brief}",
+            clause,
+        ]
+    )
+
+
+def _sanitize_brief_for_style(brief: str, style_id: str) -> str:
+    trimmed = brief.strip()
+    if style_id != "realistic":
+        return trimmed
+
+    without_conflicts = trimmed
+    for pattern in _REALISTIC_CONFLICT_PATTERNS:
+        without_conflicts = pattern.sub("", without_conflicts)
+
+    cleaned = without_conflicts
+    cleaned = re.sub(r"\s{2,}", " ", cleaned)
+    cleaned = re.sub(r"\s+([,.;:])", r"\1", cleaned)
+    cleaned = re.sub(r"(?:,\s*){2,}", ", ", cleaned)
+    cleaned = re.sub(r"\b(on|in|with|as|of)\s+(?:with|on|in|as|of)\b", r"\1", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\b(?:on|in|with|as|of)\s*([,.;:])", r"\1", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+\b(?:on|in|with|as|of)$", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"^[^\w一-鿿]+|[^\w一-鿿]+$", "", cleaned)
+    return cleaned.strip()

poetic/textfree.py

@@ -0,0 +1,20 @@
+# The one hard rule every generated background must obey: NO text in the image,
+# because the app overlays the poem/greeting itself. Defense-in-depth backstop
+# applied right before the paint call, ported from src/lib/textFree.ts.
+TEXT_FREE_RULE = (
+    "a painting only — no text, no Chinese characters, no calligraphy, no seals, no watermark"
+)
+
+FULL_BLEED_PAINTING_RULE = (
+    "full-bleed 3:4 portrait painting -- fill the entire canvas edge to edge; no borders,"
+    " no frame, no mat, no margins, no black bands, no poster layout, no split panels, no embedded text"
+)
+
+
+def ensure_text_free(brief: str, rule: str = TEXT_FREE_RULE) -> str:
+    """Return the brief guaranteed to carry the paint safety rules (appended once if missing)."""
+    guarded = brief
+    for next_rule in (FULL_BLEED_PAINTING_RULE, rule):
+        if next_rule not in guarded:
+            guarded = f"{guarded}\n\n{next_rule}"
+    return guarded

poetic/video.py

@@ -0,0 +1,35 @@
+import subprocess
+import tempfile
+
+
+def build_mux_cmd(ffmpeg: str, video_path: str, audio_path: str, out_path: str) -> list[str]:
+    """ffmpeg command that lays the song under the animation. -shortest trims the
+    longer track so a 40s song over a 4s loop doesn't produce a 40s freeze-frame —
+    instead we loop the video to the song with -stream_loop beforehand."""
+    return [
+        ffmpeg,
+        "-y",
+        "-stream_loop", "-1",
+        "-i", video_path,
+        "-i", audio_path,
+        "-map", "0:v:0",
+        "-map", "1:a:0",
+        "-c:v", "libx264",
+        "-pix_fmt", "yuv420p",
+        "-c:a", "aac",
+        "-shortest",
+        out_path,
+    ]
+
+
+def mux_song_into_video(video_path: str, audio_path: str) -> str:
+    """Loop the silent animation under the full song; returns the muxed mp4 path."""
+    import imageio_ffmpeg
+
+    out = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+    out.close()
+    cmd = build_mux_cmd(imageio_ffmpeg.get_ffmpeg_exe(), video_path, audio_path, out.name)
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg mux failed: {result.stderr[-400:]}")
+    return out.name

requirements.txt

@@ -0,0 +1,12 @@
+# spaces is intentionally NOT pinned here — the Space platform provides it.
+torch
+transformers
+diffusers
+accelerate
+safetensors
+sentencepiece
+huggingface_hub
+pillow
+imageio-ffmpeg
+gradio_client
+git+https://github.com/ace-step/ACE-Step.git

tests/test_interpretation.py

@@ -0,0 +1,47 @@
+import pytest
+
+from poetic.interpretation import build_interpret_contents, parse_interpretation
+
+
+def test_includes_poem_and_correction():
+    c = build_interpret_contents("床前明月光", "要更温暖的色调")
+    assert "床前明月光" in c
+    assert "要更温暖的色调" in c
+
+
+def test_omits_correction_line_when_none_given():
+    c = build_interpret_contents("床前明月光")
+    assert "更正" not in c
+    assert "correction" not in c.lower()
+
+
+def test_parses_guaranteed_json_into_both_fields():
+    out = parse_interpretation('{"understandingZh":"一幅月夜图","briefEn":"A moonlit night"}')
+    assert out.understanding_zh == "一幅月夜图"
+    assert out.brief_en == "A moonlit night"
+
+
+def test_raises_clear_error_on_malformed_json():
+    with pytest.raises(ValueError, match="[Ii]nterpretation"):
+        parse_interpretation("not json")
+
+
+def test_raises_when_fields_missing():
+    with pytest.raises(ValueError, match="[Ii]nterpretation"):
+        parse_interpretation('{"understandingZh":"只有一半"}')
+
+
+# The local/remote LLMs (MiniCPM, Qwen) have no enforced JSON mode like Vertex AI's
+# response schema, so the parser must repair the two common wrappings.
+
+def test_strips_markdown_code_fences():
+    text = '```json\n{"understandingZh":"月夜","briefEn":"moonlit"}\n```'
+    out = parse_interpretation(text)
+    assert out.understanding_zh == "月夜"
+    assert out.brief_en == "moonlit"
+
+
+def test_extracts_json_object_from_surrounding_prose():
+    text = '好的，以下是结果：{"understandingZh":"月夜","briefEn":"moonlit"} 希望您喜欢。'
+    out = parse_interpretation(text)
+    assert out.brief_en == "moonlit"

tests/test_motion_and_registry.py

@@ -0,0 +1,27 @@
+from poetic.motion import MOTION_CLAUSE, build_motion_prompt
+from poetic.providers import resolve_mode
+
+
+def test_motion_prompt_keeps_brief_and_adds_motion_clause():
+    out = build_motion_prompt("  A misty river at dawn.  ")
+    assert out.startswith("A misty river at dawn.")
+    assert MOTION_CLAUSE in out
+    assert "no new objects" in out
+
+
+def test_resolve_mode_defaults_to_api_off_space(monkeypatch):
+    monkeypatch.delenv("POETIC_MODE", raising=False)
+    monkeypatch.delenv("SPACES_ZERO_GPU", raising=False)
+    assert resolve_mode() == "api"
+
+
+def test_resolve_mode_defaults_to_local_on_zerogpu(monkeypatch):
+    monkeypatch.delenv("POETIC_MODE", raising=False)
+    monkeypatch.setenv("SPACES_ZERO_GPU", "true")
+    assert resolve_mode() == "local"
+
+
+def test_explicit_mode_wins(monkeypatch):
+    monkeypatch.setenv("POETIC_MODE", "api")
+    monkeypatch.setenv("SPACES_ZERO_GPU", "true")
+    assert resolve_mode() == "api"

tests/test_song.py

@@ -0,0 +1,56 @@
+from poetic.song import (
+    DEFAULT_SONG_STYLE,
+    SONG_STYLE_IDS,
+    SONG_STYLE_TAGS,
+    build_song_lyrics,
+    is_song_style_id,
+    song_tags,
+)
+
+
+def test_recognizes_only_supported_song_styles():
+    assert is_song_style_id("guofeng") is True
+    assert is_song_style_id("heavyMetal") is False
+
+
+def test_every_style_has_tags_and_default_is_valid():
+    assert set(SONG_STYLE_TAGS) == set(SONG_STYLE_IDS)
+    assert DEFAULT_SONG_STYLE in SONG_STYLE_IDS
+    for tags in SONG_STYLE_TAGS.values():
+        assert "vocal" in tags  # every preset must ask for singing, not instrumental
+
+
+def test_song_tags_falls_back_to_default_for_unknown_style():
+    assert song_tags("notAStyle") == SONG_STYLE_TAGS[DEFAULT_SONG_STYLE]
+    assert song_tags("guofeng") == SONG_STYLE_TAGS["guofeng"]
+
+
+def test_lyrics_keep_every_poem_line():
+    poem = "床前明月光，疑是地上霜。\n举头望明月，低头思故乡。"
+    lyrics = build_song_lyrics(poem)
+    for line in ("床前明月光", "疑是地上霜", "举头望明月", "低头思故乡"):
+        assert line in lyrics
+
+
+def test_lyrics_use_structure_tags():
+    lyrics = build_song_lyrics("床前明月光，疑是地上霜。举头望明月，低头思故乡。")
+    assert "[verse]" in lyrics
+    assert "[chorus]" in lyrics
+    # chorus repeats the opening couplet so the song has a memorable hook
+    assert lyrics.count("床前明月光") >= 2
+
+
+def test_lyrics_split_single_line_poem_on_chinese_punctuation():
+    lyrics = build_song_lyrics("白日依山尽，黄河入海流。欲穷千里目，更上一层楼。")
+    lines = [l for l in lyrics.splitlines() if l and not l.startswith("[")]
+    assert "白日依山尽" in lines
+    assert "更上一层楼" in lines
+    # no punctuation residue inside lyric lines
+    assert all(not any(p in l for p in "，。！？；") for l in lines)
+
+
+def test_lyrics_handle_blank_and_whitespace_input_lines():
+    lyrics = build_song_lyrics("  静夜思  \n\n床前明月光。\n")
+    lines = [l for l in lyrics.splitlines() if l and not l.startswith("[")]
+    assert "静夜思" in lines
+    assert "" not in [l.strip() for l in lines if l.strip() == ""]

tests/test_styles.py

@@ -0,0 +1,45 @@
+from poetic.styles import DEFAULT_IMAGE_STYLE, apply_image_style, is_image_style_id
+
+
+def test_recognizes_only_supported_style_ids():
+    assert is_image_style_id("inkWash") is True
+    assert is_image_style_id("posterColor") is True
+    assert is_image_style_id("oilPainting") is False
+
+
+def test_appends_curated_style_clause():
+    brief = apply_image_style("A lotus pond at dawn.", "watercolor")
+    assert "A lotus pond at dawn." in brief
+    assert "selected visual style is authoritative" in brief
+    assert "soft transparent watercolor painting" in brief
+
+
+def test_realistic_style_overrides_chinese_painting_wording():
+    brief = apply_image_style("A shui-mo Chinese painting of red flowers.", "realistic")
+    assert "Selected style / 已选画风: Realistic / 写实" in brief
+    assert "selection is mandatory" in brief
+    assert "Avoid stylized Chinese painting" in brief
+    assert "red flowers" in brief
+    assert "A shui-mo Chinese painting of red flowers." not in brief
+
+
+def test_removes_conflicting_art_direction_words_from_realistic_prompts():
+    brief = apply_image_style(
+        "A watercolor Chinese ink-wash shan-shui painting of red blossoms"
+        " on antique paper with decorative seal motifs.",
+        "realistic",
+    )
+    marker = "Real-world scene description extracted from the poem, with conflicting art-style words removed:"
+    cleaned_scene = brief.split(marker)[1].split("Make it look like a believable real-world scene first")[0]
+
+    assert "red blossoms" in cleaned_scene
+    assert "believable real-world scene" in brief
+    assert "on with" not in cleaned_scene
+    assert "watercolor Chinese ink-wash shan-shui painting" not in cleaned_scene
+    assert "antique paper" not in cleaned_scene
+    assert "decorative seal motifs" not in cleaned_scene
+
+
+def test_defaults_to_watercolor():
+    assert DEFAULT_IMAGE_STYLE == "watercolor"
+    assert "soft transparent watercolor painting" in apply_image_style("A mountain.")

tests/test_textfree.py

@@ -0,0 +1,39 @@
+from poetic.textfree import FULL_BLEED_PAINTING_RULE, TEXT_FREE_RULE, ensure_text_free
+
+
+def test_appends_canonical_no_text_rule_when_brief_omits_it():
+    out = ensure_text_free("A misty river at dawn.")
+    assert out.startswith("A misty river at dawn.")
+    assert TEXT_FREE_RULE in out
+
+
+def test_appends_full_bleed_rule_when_brief_omits_it():
+    out = ensure_text_free("A lotus pond in a classical Chinese painting style.")
+    assert FULL_BLEED_PAINTING_RULE in out
+    assert "full-bleed 3:4 portrait painting" in out
+    assert "no black bands" in out
+    assert "no split panels" in out
+
+
+def test_does_not_duplicate_text_free_rule():
+    out = ensure_text_free(f"A quiet lake. {TEXT_FREE_RULE}")
+    assert out.count(TEXT_FREE_RULE) == 1
+
+
+def test_does_not_duplicate_full_bleed_rule():
+    out = ensure_text_free(f"A quiet lake. {FULL_BLEED_PAINTING_RULE}")
+    assert out.count(FULL_BLEED_PAINTING_RULE) == 1
+
+
+def test_keeps_original_brief_intact():
+    assert "Bamboo in snow" in ensure_text_free("Bamboo in snow")
+
+
+def test_exports_exact_safety_rule_strings():
+    assert TEXT_FREE_RULE == (
+        "a painting only — no text, no Chinese characters, no calligraphy, no seals, no watermark"
+    )
+    assert FULL_BLEED_PAINTING_RULE == (
+        "full-bleed 3:4 portrait painting -- fill the entire canvas edge to edge; no borders,"
+        " no frame, no mat, no margins, no black bands, no poster layout, no split panels, no embedded text"
+    )

tests/test_video_and_card.py

@@ -0,0 +1,38 @@
+from PIL import Image
+
+from poetic.card import compose_card, layout_vertical_columns
+from poetic.video import build_mux_cmd
+
+
+def test_mux_cmd_loops_video_under_full_song():
+    cmd = build_mux_cmd("ffmpeg", "v.mp4", "a.wav", "out.mp4")
+    assert cmd[0] == "ffmpeg"
+    assert "-stream_loop" in cmd
+    assert "-shortest" in cmd
+    assert cmd[cmd.index("-i")] == "-i"
+    assert "v.mp4" in cmd and "a.wav" in cmd and cmd[-1] == "out.mp4"
+
+
+def test_vertical_columns_run_right_to_left():
+    placements = layout_vertical_columns(["床前明月光", "疑是地上霜"], 20, 6, top=10, right=300)
+    first_col_x = [x for ch, x, y in placements if ch in "床前明月光"]
+    second_col_x = [x for ch, x, y in placements if ch in "疑是地上霜"]
+    assert len(set(first_col_x)) == 1
+    assert len(set(second_col_x)) == 1
+    assert second_col_x[0] < first_col_x[0]  # second line sits to the LEFT
+
+
+def test_vertical_columns_descend_within_a_column():
+    placements = layout_vertical_columns(["床前明月光"], 20, 6, top=10, right=300)
+    ys = [y for _, _, y in placements]
+    assert ys == sorted(ys)
+    assert ys[0] == 10
+
+
+def test_compose_card_returns_same_size_image_and_does_not_mutate_input():
+    painting = Image.new("RGB", (300, 400), (240, 230, 210))
+    card = compose_card(painting, "床前明月光，疑是地上霜。", greeting="早安")
+    assert card.size == (300, 400)
+    assert card is not painting
+    # input untouched: corner pixel of the original is still the background color
+    assert painting.getpixel((5, 395)) == (240, 230, 210)