Upload folder using huggingface_hub

poetic/providers/__init__.py

@@ -1,50 +1,97 @@
 """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".
+1. Explicit per-capability env var, e.g. INTERPRET_PROVIDER=minicpm_api.
+2. POETIC_MODE bundle default for the rest.
+
+Provider names map to a module under poetic/providers/:
+- "minicpm_api"  -> OpenBMB's free hosted MiniCPM endpoint (interpret; no GPU)
+- "modal"        -> Modal serverless GPU (paint/sing/animate; sponsor prize)
+- "local"        -> on-Space ZeroGPU pipelines (local_zerogpu)
+- "api"          -> HF Inference Providers / Spaces (hf_api)
+
+POETIC_MODE bundles pick sensible defaults per capability so a single env var
+flips the whole app. The default bundle is "hosted": MiniCPM API + Modal —
+no ZeroGPU quota, qualifies for Best Use of Modal.
 """
 
 import os
 from functools import cache
 
+_MODULE_BY_NAME = {
+    "local": "local_zerogpu",
+    "api": "hf_api",
+    "minicpm_api": "minicpm_api",
+    "modal": "modal_gpu",
+}
+
+# Per-capability defaults for each POETIC_MODE bundle.
+_BUNDLES = {
+    "hosted": {  # no ZeroGPU: free MiniCPM API + Modal serverless
+        "interpret": "minicpm_api",
+        "paint": "modal",
+        "sing": "modal",
+        "animate": "modal",
+    },
+    "local": {  # everything on-Space ZeroGPU
+        "interpret": "local",
+        "paint": "local",
+        "sing": "local",
+        "animate": "local",
+    },
+    "api": {  # HF Inference Providers / Spaces everywhere
+        "interpret": "api",
+        "paint": "api",
+        "sing": "api",
+        "animate": "api",
+    },
+}
+
 
 def resolve_mode() -> str:
     mode = os.environ.get("POETIC_MODE")
-    if mode in ("local", "api"):
+    if mode in _BUNDLES:
         return mode
-    return "local" if os.environ.get("SPACES_ZERO_GPU") else "api"
+    # Default: on ZeroGPU hardware use local; otherwise the hosted bundle.
+    return "local" if os.environ.get("SPACES_ZERO_GPU") else "hosted"
+
+
+_CLASS_BY_CAPABILITY = {
+    "interpret": "Interpreter",
+    "paint": "Painter",
+    "sing": "Singer",
+    "animate": "Animator",
+}
 
 
 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:
+    name = os.environ.get(env_var) or _BUNDLES[resolve_mode()][capability]
+    module_name = _MODULE_BY_NAME.get(name)
+    if module_name is None:
         raise ValueError(
-            f"Unknown {env_var}={name!r}; expected 'local' or 'api'"
+            f"Unknown {env_var}={name!r}; expected one of {sorted(_MODULE_BY_NAME)}"
         )
-    return getattr(module, capability)()
+    import importlib
+
+    module = importlib.import_module(f"poetic.providers.{module_name}")
+    return getattr(module, _CLASS_BY_CAPABILITY[capability])()
 
 
 @cache
 def get_interpreter():
-    return _resolve("Interpreter", "INTERPRET_PROVIDER")
+    return _resolve("interpret", "INTERPRET_PROVIDER")
 
 
 @cache
 def get_painter():
-    return _resolve("Painter", "PAINT_PROVIDER")
+    return _resolve("paint", "PAINT_PROVIDER")
 
 
 @cache
 def get_singer():
-    return _resolve("Singer", "SING_PROVIDER")
+    return _resolve("sing", "SING_PROVIDER")
 
 
 @cache
 def get_animator():
-    return _resolve("Animator", "ANIMATE_PROVIDER")
+    return _resolve("animate", "ANIMATE_PROVIDER")

poetic/providers/minicpm_api.py

@@ -0,0 +1,45 @@
+"""Interpret via OpenBMB's free hosted MiniCPM endpoint — no GPU, no quota.
+
+The hackathon provides a free MiniCPM4.1-8B OpenAI-compatible API. Using it for
+读诗 means the Space needs no GPU for interpretation at all, and keeps the
+sponsor (OpenBMB) model in the pipeline for the Best MiniCPM Build prize.
+"""
+
+import os
+import re
+
+import requests
+
+from poetic.interpretation import Interpretation, build_interpret_contents, parse_interpretation
+from poetic.prompts import INTERPRET_SYSTEM_PROMPT
+
+DEFAULT_BASE_URL = "http://35.203.155.71:8001"
+DEFAULT_MODEL = "MiniCPM4.1-8B"
+
+# MiniCPM4.1 is a reasoning model; strip any <think>…</think> the server still emits.
+_THINK_RE = re.compile(r"<think>.*?</think>", re.DOTALL)
+
+
+class Interpreter:
+    def interpret(self, poem: str, correction: str | None = None) -> Interpretation:
+        base = os.environ.get("MINICPM_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+        key = os.environ.get("OPENBMB_API_KEY") or os.environ.get("MINICPM_API_KEY")
+        response = requests.post(
+            f"{base}/v1/chat/completions",
+            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            json={
+                "model": os.environ.get("MINICPM_MODEL", DEFAULT_MODEL),
+                "messages": [
+                    {"role": "system", "content": INTERPRET_SYSTEM_PROMPT},
+                    {"role": "user", "content": build_interpret_contents(poem, correction)},
+                ],
+                "max_tokens": 1024,
+                "temperature": 0.7,
+                # Disable chain-of-thought so the reply is clean JSON.
+                "chat_template_kwargs": {"enable_thinking": False},
+            },
+            timeout=float(os.environ.get("MINICPM_TIMEOUT", "60")),
+        )
+        response.raise_for_status()
+        content = response.json()["choices"][0]["message"]["content"]
+        return parse_interpretation(_THINK_RE.sub("", content).strip())

poetic/providers/modal_gpu.py

@@ -0,0 +1,85 @@
+"""Heavy pipelines (paint / sing / animate) on Modal serverless GPU.
+
+Modal is a hackathon sponsor (Best Use of Modal). Running FLUX.2 Klein,
+ACE-Step and Wan2.2 as Modal functions removes the ZeroGPU daily-quota ceiling
+and keeps the Space itself GPU-free — the Space only needs to call out.
+
+The Modal app (deployed separately via `modal deploy modal_app.py`) exposes
+three web endpoints; these adapters POST to them. Configure with:
+  MODAL_PAINT_URL / MODAL_SING_URL / MODAL_ANIMATE_URL  (+ MODAL_TOKEN optional)
+
+NOTE: scaffolding for the approved compute-swap. The Modal app + live wiring is
+the next build step; these adapters fail loudly until the URLs are set.
+"""
+
+import base64
+import io
+import os
+import tempfile
+
+import requests
+from PIL import Image
+
+_TIMEOUT = float(os.environ.get("MODAL_TIMEOUT", "600"))
+
+
+def _endpoint(env_var: str) -> str:
+    url = os.environ.get(env_var)
+    if not url:
+        raise RuntimeError(
+            f"{env_var} is not set — deploy the Modal app and set its endpoint URLs. "
+            "Until then use a different provider (e.g. PAINT_PROVIDER=api)."
+        )
+    return url
+
+
+def _headers() -> dict:
+    token = os.environ.get("MODAL_TOKEN")
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+class Painter:
+    def paint(self, brief: str) -> Image.Image:
+        resp = requests.post(
+            _endpoint("MODAL_PAINT_URL"),
+            headers=_headers(),
+            json={"brief": brief, "width": 768, "height": 1024},
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        return Image.open(io.BytesIO(resp.content)).convert("RGB")
+
+
+class Singer:
+    def sing(self, tags: str, lyrics: str, duration: float = 40.0) -> str:
+        resp = requests.post(
+            _endpoint("MODAL_SING_URL"),
+            headers=_headers(),
+            json={"tags": tags, "lyrics": lyrics, "duration": duration},
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        out = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+        out.write(resp.content)
+        out.close()
+        return out.name
+
+
+class Animator:
+    def animate(self, image: Image.Image, brief: str) -> str:
+        buf = io.BytesIO()
+        image.convert("RGB").save(buf, format="PNG")
+        resp = requests.post(
+            _endpoint("MODAL_ANIMATE_URL"),
+            headers=_headers(),
+            json={
+                "brief": brief,
+                "image_b64": base64.b64encode(buf.getvalue()).decode(),
+            },
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        out = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+        out.write(resp.content)
+        out.close()
+        return out.name