Sync Dream Customs UI voice settings

.gitattributes

@@ -33,6 +33,3 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
-docs/design/assets/dream-customs-probe-morning-console.png filter=lfs diff=lfs merge=lfs -text
-docs/design/assets/dream-customs-probe-night-border.png filter=lfs diff=lfs merge=lfs -text
-docs/design/assets/dream-customs-probe-night-desk.png filter=lfs diff=lfs merge=lfs -text

AGENTS.md

@@ -70,6 +70,9 @@
 - 如果需要正式提交，先确认是否已初始化/切换到 Dream Customs 专用仓库。
 - 在仓库归属未确认前，可以本地写文件，但不要强行 `git add` / `git commit` / `git push` 到父级 VLA 仓库。
 - 如果建立新功能分支，使用 `feature/xxx` 命名。
+- 用户要求修改完成后，默认不仅推送 GitHub 分支，也要同步提交到 Hugging Face Space，并完成可用的 merge / 部署路径；不要只停在本地或 GitHub 分支。
+- 同步 HF Space 前先确认 `space` remote 指向 `build-small-hackathon/dream-customs`，并复核当前分支与提交 SHA，避免误推到其他 Space 或父级仓库。
+- 如果 HF Space 同步涉及密钥、账单、权限弹窗、强制覆盖公开 `main`、或无法自动 merge 的 PR/Discussion，则先说明具体阻塞并请求用户确认；不要打印或保存任何 token。
 
 ## 实现原则
 

README.md

@@ -65,13 +65,17 @@ Local smoke notes from this Mac mini:
 
 ## Optional Hosted MiniCPM Routes
 
-Hosted routes are intended for Modal experiments or private Space secrets. Set these in the runtime environment only, then switch the UI route menus from `demo` to `model`:
+The public Space stays lightweight and can call private Modal endpoints through runtime secrets:
 
-- `DREAM_CUSTOMS_TEXT_ENDPOINT`
-- `DREAM_CUSTOMS_VISION_ENDPOINT`
-- `DREAM_CUSTOMS_HOSTED_TOKEN`
+- `DREAM_CUSTOMS_TEXT_ENDPOINT`: Modal text route for `openbmb/MiniCPM5-1B`.
+- `DREAM_CUSTOMS_VISION_ENDPOINT`: Modal vision route for `openbmb/MiniCPM-V-4.6`.
+- `DREAM_CUSTOMS_HOSTED_TOKEN`: shared bearer token checked by Modal and sent by the Space.
 
-Missing endpoints or route failures fall back to deterministic demo behavior. Do not store token values in env files, git, docs, screenshots, logs, or examples.
+Set these only as Hugging Face Space repository secrets or local shell variables. Do not store values in `.env`, docs, logs, screenshots, or git. Missing endpoints or route failures fall back to deterministic demo behavior.
+
+The Gradio UI defaults to `model` for both text and vision backends, so a configured Space calls Modal by default. The `demo` backend remains available in developer settings as the deterministic fallback path.
+
+The Hugging Face Space may run on ZeroGPU for hackathon hardware eligibility. `dream_customs.zerogpu` registers a lightweight `@spaces.GPU` startup probe so ZeroGPU accepts the app, but real MiniCPM inference still happens on the private Modal backend.
 
 Token-safe text smoke:
 
@@ -114,7 +118,7 @@ python -m pytest -q
 
 2026-06-05 local V2 verification passed: tests were green and the workbench flow reached a sealed pact through `Send to customs`, `Ask another question`, `Add material`, `Draft pact`, `Revise pact`, and `Seal today's pact`.
 
-The public Space now serves the V2 workbench from Space `main` commit `8ad6f00628f800abc2dbefab05163aba94a5723f`. Public browser smoke, mobile readability, diagnostics, raw remote queue prediction, and a hosted text route smoke all reached a sealed pact. Hosted vision route smoke remains optional for the next pass.
+The public Space now serves the V2 workbench from Space `main` commit `8ad6f00628f800abc2dbefab05163aba94a5723f`. Public browser smoke, mobile readability, diagnostics, raw remote queue prediction, and a hosted text route smoke all reached a sealed pact on 2026-06-05. The current Modal backend pass requires a real `openbmb/MiniCPM-V-4.6` vision route smoke before delivery; demo vision fallback is runtime resilience, not a substitute for that smoke.
 
 Current smoke details are tracked in `docs/smoke/2026-06-05-space-deployment-smoke.md`.
 

docs/goal-prompts/2026-06-06-modal-minicpm-backend.md

@@ -0,0 +1,9 @@
+# Modal MiniCPM Backend Goal Prompt
+
+在 `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon` 继续 Dream Customs。先读 `AGENTS.md`、`docs/spec.md`、`docs/prd.md`、`docs/handoff.md` 和 `docs/superpowers/plans/2026-06-06-modal-minicpm-backend.md`。
+
+执行计划：用 `feature/modal-minicpm-backend` 分支，按任务勾选推进，部署 Modal 作为隐藏 MiniCPM 后端，HF Space 继续做 Gradio 前台。
+
+硬约束：严禁把任何 token、endpoint secret、HF token、Modal token 写入仓库、日志、文档或截图；只记录变量名和非敏感 smoke 结果。开工前先确认 HF Space secrets 是否已存在；缺失或需要用户填写时立刻停下请求用户处理。默认 backend 保持 `demo`，`model` route 只能作为可切换真实推理路径，失败必须 fallback。MiniCPM-V-4.6 vision route 是硬验收，不允许用 demo vision 或跳过 vision smoke 代替；如果 GPU 不够，升级 Modal GPU，但不要换非 MiniCPM-V-4.6 模型。不要扩展到非 MiniCPM 模型；语音 ASR 不在本轮范围。
+
+验收：每个任务完成后运行相应 pytest/smoke，更新计划 checkbox，分步提交；最后 push 分支并汇报 Modal text smoke、Modal MiniCPM-V-4.6 vision smoke、12 条 eval、Space model route 和 demo fallback 结果。

docs/handoff.md

@@ -133,6 +133,21 @@ This directory is now a dedicated Dream Customs repository:
 
 Continue to confirm `git remote -v` before pushing, but the earlier VLA remote warning is no longer the active state.
 
+## Modal Backend Route
+
+The intended production-quality route is:
+
+```text
+Hugging Face Space Gradio UI
+  -> HostedMiniCPMTextClient / HostedMiniCPMVisionClient
+  -> private Modal endpoints
+  -> MiniCPM5-1B text generation and MiniCPM-V-4.6 visual clue extraction
+```
+
+The Space defaults to `model` for both text and vision backends, so a configured Space calls Modal immediately. The `demo` backend remains available in developer settings as the deterministic fallback path.
+
+The public Space can run on ZeroGPU after `dream_customs.zerogpu` registers the lightweight `@spaces.GPU` startup probe. Modal credits still pay for the hidden L4 GPU backend; the ZeroGPU probe is only there to make the HF hardware setting valid for this Gradio frontend.
+
 ## Open Questions For User
 
 These do not block initial scaffolding:

docs/smoke/2026-06-06-modal-minicpm-backend-smoke.md

@@ -0,0 +1,30 @@
+# Modal MiniCPM Backend Smoke - 2026-06-06
+
+## Scope
+
+- Modal app: `dream-customs-minicpm-backend`
+- Text model: `openbmb/MiniCPM5-1B`
+- Vision model: `openbmb/MiniCPM-V-4.6`
+- Public UI remains Hugging Face Space `build-small-hackathon/dream-customs`
+- Secrets and endpoint values were not printed, documented, or committed.
+
+## Results
+
+- Health endpoint: PASS
+- Text smoke: PASS with `text_route=ok` and `text_questions=2`
+- Vision smoke: PASS with `vision_route=ok` and `vision_clues=8`
+- Acceptance eval: PASS with `passed=12`, `total=12`, `schema_valid_rate=1.0`, and `failures=[]`
+- Hugging Face Space model route: PASS with `status=negotiating`, `text_backend=model`, `vision_backend=model`, one extracted image evidence item, and `visual_clue_count=8`
+- Hugging Face Space demo fallback: PASS with `status=negotiating`, `text_backend=demo`, `vision_backend=demo`, one extracted image evidence item, and `visual_clue_count=3`
+- Hugging Face Space hardware recovery: PASS after switching the Space from ZeroGPU back to `CPU basic`; public model route and demo fallback were re-smoked successfully.
+- ZeroGPU compatibility fix: PASS after adding the `@spaces.GPU` startup probe and making `model` the default backend.
+- Hugging Face Space ZeroGPU default model route: PASS with `hardware=zero-a10g`, `status=negotiating`, `text_backend=model`, `vision_backend=model`, one extracted image evidence item, and `visual_clue_count=8`
+- Hugging Face Space ZeroGPU demo fallback: PASS with `hardware=zero-a10g`, `status=negotiating`, `text_backend=demo`, `vision_backend=demo`, one extracted image evidence item, and `visual_clue_count=3`
+
+## Notes
+
+- GPU class remained `L4`; no upgrade was required for `openbmb/MiniCPM-V-4.6`.
+- Modal text output keeps the real MiniCPM route first and repairs missing JSON fields only when schema validation would otherwise fail.
+- Hugging Face Space secret sync was first attempted through the local HF token, but the API returned a non-secret `403 Forbidden: Authorization error`.
+- The three Space secrets were replaced through the logged-in Hugging Face UI, then the Space was restarted and verified through the public Gradio API.
+- The public Gradio Space can run on ZeroGPU once the lightweight `@spaces.GPU` startup probe is present. Modal credits still cover the L4 GPU inference backend, and `model` is now the default text and vision backend.

docs/superpowers/plans/2026-06-06-modal-minicpm-backend.md

@@ -0,0 +1,1226 @@
+# Modal MiniCPM Backend Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Use the available Modal credits to deploy real MiniCPM text and vision inference endpoints, then connect the existing Hugging Face Space UI through private runtime secrets while preserving the deterministic demo fallback.
+
+**Architecture:** Keep Hugging Face Space as the public Gradio frontend and use Modal as a hidden GPU backend. Modal exposes one text endpoint for `openbmb/MiniCPM5-1B` JSON generation and one vision endpoint for `openbmb/MiniCPM-V-4.6` visual clue extraction. The existing `HostedMiniCPMTextClient` and `HostedMiniCPMVisionClient` continue to call plain JSON HTTP endpoints through `DREAM_CUSTOMS_TEXT_ENDPOINT`, `DREAM_CUSTOMS_VISION_ENDPOINT`, and `DREAM_CUSTOMS_HOSTED_TOKEN`.
+
+**Tech Stack:** Python, Modal, FastAPI endpoint decorators, Transformers, PyTorch, Pillow, Gradio, Hugging Face Space repository secrets, pytest.
+
+---
+
+## Scope And Non-Negotiables
+
+- Do not replace the public Hugging Face Space with Modal.
+- Do not store endpoint tokens, Hugging Face tokens, Modal tokens, or secret values in git, docs, logs, screenshots, or example files.
+- Keep the UI default backend as `demo`.
+- Keep text-only demo fallback working when Modal endpoints are missing, cold, slow, or failing.
+- Keep the model family constrained to `MiniCPM` before trying unrelated small models.
+- Completion requires a working `MiniCPM-V-4.6` vision route. Demo vision fallback is allowed only as runtime resilience after the real vision route has passed smoke; it is not an acceptable substitute for final delivery.
+- Confirm Hugging Face Space secrets at the start of execution. If the Space is missing required secrets or needs updated Modal endpoint values, stop early and ask the user to fill or approve filling them before remote Space verification.
+- Treat voice transcription as unchanged for this pass; ASR remains fake/demo unless a separate plan approves a real ASR adapter.
+
+## File Structure
+
+- Create `modal_backend/__init__.py`: package marker for Modal backend helpers.
+- Create `modal_backend/contracts.py`: pure request/response helpers that are importable by tests without importing `modal`, `torch`, or `transformers`.
+- Create `modal_backend/dream_customs_modal.py`: Modal app definition, GPU classes, model loading, authentication, `/text`, `/vision`, and health endpoint.
+- Create `tests/test_modal_contract.py`: fast local contract tests for request parsing, image decoding, auth behavior, and response shape.
+- Create `scripts/smoke_hosted_routes.py`: local smoke script that calls configured hosted endpoints without printing secret values.
+- Create `scripts/eval_hosted_routes.py`: small acceptance evaluator for schema validity, safety edge cases, and vision clue extraction.
+- Modify `README.md`: add Modal deployment and HF Space secret setup instructions.
+- Modify `docs/handoff.md`: record the intended production route and fallback contract.
+- Modify `docs/smoke/2026-06-06-modal-minicpm-backend-smoke.md`: capture smoke results after deployment.
+
+## Task 0: Prepare The Branch And Baseline
+
+**Files:**
+- Read: `AGENTS.md`
+- Read: `docs/spec.md`
+- Read: `docs/prd.md`
+- Read: `docs/handoff.md`
+- Read: `dream_customs/models.py`
+- Read: `dream_customs/app_logic.py`
+
+- [x] **Step 1: Confirm repository and branch**
+
+Run:
+
+```bash
+pwd
+git status --short --branch
+git remote -v
+```
+
+Expected:
+
+```text
+/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon
+## feature/dream-customs-mvp...origin/feature/dream-customs-mvp
+origin  https://github.com/adjcjh777/dream-customs-build-small.git (fetch)
+origin  https://github.com/adjcjh777/dream-customs-build-small.git (push)
+```
+
+- [x] **Step 2: Sync latest code**
+
+Run:
+
+```bash
+git pull
+```
+
+Expected:
+
+```text
+Already up to date.
+```
+
+If remote changes arrive, read them before editing and keep this plan aligned with the current file names.
+
+- [x] **Step 3: Create implementation branch**
+
+Run:
+
+```bash
+git switch -c feature/modal-minicpm-backend
+```
+
+Expected:
+
+```text
+Switched to a new branch 'feature/modal-minicpm-backend'
+```
+
+- [x] **Step 4: Run baseline tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all existing tests pass.
+
+- [x] **Step 5: Confirm Hugging Face Space secret readiness**
+
+Before writing backend code, open the Hugging Face Space settings for `build-small-hackathon/dream-customs` and confirm whether these repository secrets already exist:
+
+```text
+DREAM_CUSTOMS_TEXT_ENDPOINT
+DREAM_CUSTOMS_VISION_ENDPOINT
+DREAM_CUSTOMS_HOSTED_TOKEN
+```
+
+Expected: the secrets exist, or the worker has stopped and asked the user to fill them before public Space verification. Do not print or copy secret values. If the Modal endpoint URLs will be newly generated later, record only this non-secret status in your notes:
+
+```text
+HF Space secrets preflight: present, may need endpoint value refresh after Modal deploy.
+```
+
+Commit is not needed for this task.
+
+Observed 2026-06-06: required secret keys/value readiness was confirmed by the user. Endpoint values still need refresh after Modal deploy. No secret values were recorded.
+
+## Task 1: Add Pure Modal Endpoint Contract Helpers
+
+**Files:**
+- Create: `modal_backend/__init__.py`
+- Create: `modal_backend/contracts.py`
+- Create: `tests/test_modal_contract.py`
+
+- [x] **Step 1: Write failing contract tests**
+
+Create `tests/test_modal_contract.py`:
+
+```python
+import base64
+
+from modal_backend.contracts import (
+    AuthError,
+    decode_image_payload,
+    ensure_authorized,
+    normalize_text_payload,
+    response_payload,
+)
+
+
+def test_normalize_text_payload_accepts_prompt():
+    payload = normalize_text_payload({"prompt": "Return JSON.", "max_tokens": 123})
+    assert payload["prompt"] == "Return JSON."
+    assert payload["max_tokens"] == 123
+    assert payload["temperature"] == 0.2
+
+
+def test_normalize_text_payload_accepts_openai_style_messages():
+    payload = normalize_text_payload(
+        {"messages": [{"role": "user", "content": "Dream of an elevator."}]}
+    )
+    assert payload["prompt"] == "Dream of an elevator."
+    assert payload["max_tokens"] == 700
+
+
+def test_normalize_text_payload_clamps_max_tokens():
+    payload = normalize_text_payload({"prompt": "x", "max_tokens": 9000})
+    assert payload["max_tokens"] == 1200
+
+
+def test_decode_image_payload_accepts_image_key():
+    encoded = base64.b64encode(b"fake-image-bytes").decode("ascii")
+    assert decode_image_payload({"image": encoded}) == b"fake-image-bytes"
+
+
+def test_decode_image_payload_accepts_images_list():
+    encoded = base64.b64encode(b"fake-image-bytes").decode("ascii")
+    assert decode_image_payload({"images": [encoded]}) == b"fake-image-bytes"
+
+
+def test_response_payload_uses_existing_client_shape():
+    assert response_payload("hello") == {"response": "hello"}
+
+
+def test_ensure_authorized_allows_empty_expected_token_for_local_smoke():
+    ensure_authorized("", "")
+
+
+def test_ensure_authorized_accepts_bearer_token():
+    ensure_authorized("Bearer secret-value", "secret-value")
+
+
+def test_ensure_authorized_rejects_wrong_token():
+    try:
+        ensure_authorized("Bearer wrong", "secret-value")
+    except AuthError as exc:
+        assert str(exc) == "Unauthorized hosted route request."
+    else:
+        raise AssertionError("Expected AuthError")
+```
+
+- [x] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_modal_contract.py -q
+```
+
+Expected:
+
+```text
+ModuleNotFoundError: No module named 'modal_backend'
+```
+
+- [x] **Step 3: Create package marker**
+
+Create `modal_backend/__init__.py`:
+
+```python
+"""Modal backend package for Dream Customs."""
+```
+
+- [x] **Step 4: Implement pure endpoint contract helpers**
+
+Create `modal_backend/contracts.py`:
+
+```python
+import base64
+from typing import Any, Dict
+
+
+class AuthError(Exception):
+    """Raised when a hosted route request is not authorized."""
+
+
+def _clean_text(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def normalize_text_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    prompt = _clean_text(payload.get("prompt"))
+    if not prompt:
+        messages = payload.get("messages")
+        if isinstance(messages, list):
+            parts = []
+            for item in messages:
+                if isinstance(item, dict):
+                    content = _clean_text(item.get("content"))
+                    if content:
+                        parts.append(content)
+            prompt = "\n".join(parts).strip()
+    max_tokens = payload.get("max_tokens", 700)
+    try:
+        max_tokens = int(max_tokens)
+    except (TypeError, ValueError):
+        max_tokens = 700
+    max_tokens = max(64, min(max_tokens, 1200))
+    temperature = payload.get("temperature", 0.2)
+    try:
+        temperature = float(temperature)
+    except (TypeError, ValueError):
+        temperature = 0.2
+    temperature = max(0.0, min(temperature, 0.7))
+    return {
+        "prompt": prompt,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+    }
+
+
+def decode_image_payload(payload: Dict[str, Any]) -> bytes:
+    encoded = payload.get("image")
+    if not encoded and isinstance(payload.get("images"), list) and payload["images"]:
+        encoded = payload["images"][0]
+    if not encoded:
+        raise ValueError("Missing image payload.")
+    if isinstance(encoded, bytes):
+        encoded = encoded.decode("ascii")
+    return base64.b64decode(str(encoded))
+
+
+def ensure_authorized(authorization_header: str, expected_token: str) -> None:
+    expected_token = expected_token.strip()
+    if not expected_token:
+        return
+    header = authorization_header.strip()
+    if header.lower().startswith("bearer "):
+        supplied = header.split(" ", 1)[1].strip()
+    else:
+        supplied = header
+    if supplied != expected_token:
+        raise AuthError("Unauthorized hosted route request.")
+
+
+def response_payload(text: str) -> Dict[str, str]:
+    return {"response": text}
+```
+
+- [x] **Step 5: Run contract tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_modal_contract.py -q
+```
+
+Expected:
+
+```text
+9 passed
+```
+
+- [x] **Step 6: Run full tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all tests pass.
+
+- [x] **Step 7: Commit contract helpers**
+
+Run:
+
+```bash
+git add modal_backend/__init__.py modal_backend/contracts.py tests/test_modal_contract.py
+git commit -m "test: add modal endpoint contract helpers"
+```
+
+## Task 2: Add Modal Text And Vision Services
+
+**Files:**
+- Create: `modal_backend/dream_customs_modal.py`
+- Modify: `requirements.txt`
+
+- [x] **Step 1: Decide dependency placement**
+
+Keep Modal-only dependencies inside the Modal image in `modal_backend/dream_customs_modal.py`. Do not add `modal`, `torch`, or heavy Transformers-only deployment packages to `requirements.txt` unless local tests need them. The public Hugging Face Space should stay lightweight.
+
+- [x] **Step 2: Create Modal service file**
+
+Create `modal_backend/dream_customs_modal.py`:
+
+```python
+import io
+import os
+import tempfile
+from typing import Any, Dict
+
+import modal
+
+from modal_backend.contracts import (
+    AuthError,
+    decode_image_payload,
+    ensure_authorized,
+    normalize_text_payload,
+    response_payload,
+)
+
+
+APP_NAME = "dream-customs-minicpm-backend"
+TEXT_MODEL = "openbmb/MiniCPM5-1B"
+VISION_MODEL = "openbmb/MiniCPM-V-4.6"
+MINUTES = 60
+
+app = modal.App(APP_NAME)
+
+hf_cache = modal.Volume.from_name("dream-customs-hf-cache", create_if_missing=True)
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .apt_install("git")
+    .pip_install(
+        "accelerate",
+        "einops",
+        "fastapi[standard]",
+        "pillow",
+        "protobuf",
+        "sentencepiece",
+        "torch",
+        "torchvision",
+        "transformers>=4.56",
+    )
+)
+
+secrets = [modal.Secret.from_name("dream-customs-modal-secrets")]
+
+
+def _auth_header(request: Any) -> str:
+    return str(request.headers.get("authorization", ""))
+
+
+def _expected_token() -> str:
+    return os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", "").strip()
+
+
+def _json_error(message: str, status: str = "error") -> Dict[str, str]:
+    return {"status": status, "response": "", "error": message}
+
+
+@app.function(image=image, secrets=secrets)
+@modal.fastapi_endpoint(method="GET", docs=True)
+def health() -> Dict[str, str]:
+    return {
+        "status": "ok",
+        "app": APP_NAME,
+        "text_model": TEXT_MODEL,
+        "vision_model": VISION_MODEL,
+    }
+
+
+@app.cls(
+    image=image,
+    gpu="L4",
+    timeout=10 * MINUTES,
+    scaledown_window=5 * MINUTES,
+    volumes={"/root/.cache/huggingface": hf_cache},
+    secrets=secrets,
+)
+class TextService:
+    @modal.enter()
+    def load(self):
+        from transformers import pipeline
+
+        self.pipe = pipeline(
+            "text-generation",
+            model=os.getenv("DREAM_CUSTOMS_TEXT_MODEL", TEXT_MODEL),
+            device_map="auto",
+            torch_dtype="auto",
+            trust_remote_code=True,
+        )
+
+    @modal.fastapi_endpoint(method="POST", docs=True)
+    async def text(self, request):
+        try:
+            ensure_authorized(_auth_header(request), _expected_token())
+        except AuthError as exc:
+            return _json_error(str(exc), status="unauthorized")
+        payload = await request.json()
+        normalized = normalize_text_payload(payload)
+        if not normalized["prompt"]:
+            return _json_error("Missing prompt.")
+        output = self.pipe(
+            normalized["prompt"],
+            max_new_tokens=normalized["max_tokens"],
+            do_sample=normalized["temperature"] > 0,
+            temperature=max(normalized["temperature"], 0.01),
+            return_full_text=False,
+        )
+        text = str(output[0].get("generated_text", "")).strip()
+        return response_payload(text)
+
+
+@app.cls(
+    image=image,
+    gpu="L4",
+    timeout=10 * MINUTES,
+    scaledown_window=5 * MINUTES,
+    volumes={"/root/.cache/huggingface": hf_cache},
+    secrets=secrets,
+)
+class VisionService:
+    @modal.enter()
+    def load(self):
+        from transformers import pipeline
+
+        self.pipe = pipeline(
+            "image-text-to-text",
+            model=os.getenv("DREAM_CUSTOMS_VISION_MODEL", VISION_MODEL),
+            device_map="auto",
+            torch_dtype="auto",
+            trust_remote_code=True,
+        )
+
+    @modal.fastapi_endpoint(method="POST", docs=True)
+    async def vision(self, request):
+        try:
+            ensure_authorized(_auth_header(request), _expected_token())
+        except AuthError as exc:
+            return _json_error(str(exc), status="unauthorized")
+        payload = await request.json()
+        prompt = str(payload.get("prompt") or "").strip()
+        if not prompt:
+            prompt = (
+                "Extract concise dream-like visual clues from this image. "
+                "Return a single JSON object with keys objects, places, visible_text, "
+                "colors, mood_cues, and uncertain_details. Do not diagnose."
+            )
+        try:
+            image_bytes = decode_image_payload(payload)
+        except ValueError as exc:
+            return _json_error(str(exc))
+        from PIL import Image
+
+        pil_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+        with tempfile.NamedTemporaryFile(suffix=".png") as temp_file:
+            pil_image.save(temp_file.name)
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image", "path": temp_file.name},
+                        {"type": "text", "text": prompt},
+                    ],
+                }
+            ]
+            result = self.pipe(text=messages, max_new_tokens=int(payload.get("max_tokens", 320)))
+        return response_payload(str(result).strip())
+```
+
+- [x] **Step 3: Run import check without requiring Modal locally**
+
+Run:
+
+```bash
+.venv/bin/python - <<'PY'
+from modal_backend.contracts import response_payload
+print(response_payload("ok"))
+PY
+```
+
+Expected:
+
+```text
+{'response': 'ok'}
+```
+
+- [x] **Step 4: Run tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all tests pass.
+
+- [x] **Step 5: Commit Modal service scaffold**
+
+Run:
+
+```bash
+git add modal_backend/dream_customs_modal.py
+git commit -m "feat: add modal minicpm backend service"
+```
+
+## Task 3: Validate Modal Service Locally With `modal serve`
+
+**Files:**
+- Read: `modal_backend/dream_customs_modal.py`
+
+- [x] **Step 1: Confirm Modal CLI is authenticated**
+
+Run:
+
+```bash
+modal token set --help >/dev/null && modal profile current
+```
+
+Expected: a Modal profile for workspace `cjh-12569` or a clear CLI message requiring login.
+
+If login is required, run:
+
+```bash
+modal setup
+```
+
+Complete browser login for workspace `cjh-12569`.
+
+- [x] **Step 2: Create Modal secret without printing values**
+
+Run with values pasted only into the command invocation, not into a file:
+
+```bash
+modal secret create dream-customs-modal-secrets \
+  HF_TOKEN="$HF_TOKEN" \
+  DREAM_CUSTOMS_HOSTED_TOKEN="$DREAM_CUSTOMS_HOSTED_TOKEN"
+```
+
+Expected:
+
+```text
+Created secret dream-customs-modal-secrets
+```
+
+If the secret already exists, update it from the Modal dashboard or recreate it after confirming no unrelated app depends on it.
+
+Observed 2026-06-06: Modal CLI authenticated to workspace `cjh-12569`; Modal secret `dream-customs-modal-secrets` exists. Secret values were not printed or recorded. The hosted token still needs to be synchronized with the Hugging Face Space secret before public Space model-route verification.
+
+- [x] **Step 3: Serve or deploy the Modal app for development validation**
+
+Run:
+
+```bash
+modal serve modal_backend/dream_customs_modal.py
+```
+
+Expected: Modal prints development endpoint URLs for `health`, `text`, and `vision`. Do not paste secret-bearing URLs or tokens into logs.
+
+Observed 2026-06-06: skipped long-running `modal serve` in favor of `modal deploy` plus SDK endpoint discovery. Endpoint URLs were kept in-process only and were not written to docs, logs, screenshots, or git.
+
+- [x] **Step 4: Check health endpoint**
+
+In a second terminal, run with the health URL copied from Modal output:
+
+```bash
+curl -s "$DREAM_CUSTOMS_MODAL_HEALTH_URL" | .venv/bin/python -m json.tool
+```
+
+Expected:
+
+```json
+{
+  "status": "ok",
+  "app": "dream-customs-minicpm-backend",
+  "text_model": "openbmb/MiniCPM5-1B",
+  "vision_model": "openbmb/MiniCPM-V-4.6"
+}
+```
+
+Observed 2026-06-06: health smoke passed after deployment.
+
+- [x] **Step 5: Smoke text endpoint with token-safe output**
+
+Run:
+
+```bash
+.venv/bin/python - <<'PY'
+import json
+import os
+import urllib.request
+
+payload = {
+    "prompt": "Return only JSON: {\"visitor_name\":\"Gate 14\",\"questions\":[\"What does it ask?\"],\"tone_note\":\"gentle\"}",
+    "max_tokens": 180,
+}
+request = urllib.request.Request(
+    os.environ["DREAM_CUSTOMS_TEXT_ENDPOINT"],
+    data=json.dumps(payload).encode("utf-8"),
+    headers={
+        "Content-Type": "application/json",
+        "Authorization": "Bearer " + os.environ["DREAM_CUSTOMS_HOSTED_TOKEN"],
+    },
+    method="POST",
+)
+with urllib.request.urlopen(request, timeout=180) as response:
+    data = json.loads(response.read().decode("utf-8"))
+print({"has_response": bool(data.get("response")), "status": data.get("status", "ok")})
+PY
+```
+
+Expected:
+
+```text
+{'has_response': True, 'status': 'ok'}
+```
+
+Observed 2026-06-06: strict hosted smoke passed with `text_route=ok` and `text_questions=2`.
+
+- [x] **Step 6: Record any GPU/load failure**
+
+If Modal fails because `MiniCPM-V-4.6` does not fit on `L4`, change only `VisionService.gpu` to `A10G` first. If it still fails, change only `VisionService.gpu` to `L40S`; if `L40S` still fails, try `A100-40GB`, then `A100-80GB`. Keep `TextService.gpu` on `L4` unless text loading fails. Do not switch away from `openbmb/MiniCPM-V-4.6` to satisfy the vision requirement; if all GPU classes fail, mark the goal blocked with the exact non-secret Modal load error.
+
+Observed 2026-06-06: no GPU upgrade was required. Text and vision routes both passed on `L4`.
+
+- [x] **Step 7: Commit GPU adjustment if needed**
+
+Run only if the service file changed:
+
+```bash
+git add modal_backend/dream_customs_modal.py
+git commit -m "fix: tune modal gpu class for minicpm backend"
+```
+
+Observed 2026-06-06: no GPU-class adjustment commit was needed.
+
+## Task 4: Add Token-Safe Hosted Route Smoke Script
+
+**Files:**
+- Create: `scripts/smoke_hosted_routes.py`
+
+- [x] **Step 1: Create smoke script**
+
+Create `scripts/smoke_hosted_routes.py`:
+
+```python
+import json
+import os
+import sys
+from pathlib import Path
+
+from dream_customs.models import HostedMiniCPMTextClient, HostedMiniCPMVisionClient
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name, "").strip()
+    if not value:
+        raise SystemExit(f"Missing required environment variable: {name}")
+    return value
+
+
+def main() -> int:
+    token = os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", "")
+    text_endpoint = _require("DREAM_CUSTOMS_TEXT_ENDPOINT")
+    vision_endpoint = _require("DREAM_CUSTOMS_VISION_ENDPOINT")
+    image_path = _require("DREAM_CUSTOMS_SMOKE_IMAGE")
+    if not Path(image_path).exists():
+        raise SystemExit("DREAM_CUSTOMS_SMOKE_IMAGE does not exist.")
+    text_client = HostedMiniCPMTextClient(endpoint=text_endpoint, token=token, timeout=180)
+    negotiation = text_client.generate_negotiation(
+        "我梦见自己在深夜海关排队，口袋里装着一枚蓝色印章。"
+    )
+    text_ok = bool(negotiation.get("visitor_name")) and bool(negotiation.get("questions"))
+    result = {
+        "text_route": "ok" if text_ok else "failed",
+        "text_questions": len(negotiation.get("questions", [])),
+        "vision_route": "failed",
+        "vision_clues": 0,
+    }
+    vision_client = HostedMiniCPMVisionClient(endpoint=vision_endpoint, token=token, timeout=180)
+    clues = vision_client.extract_clues(image_path)
+    result["vision_route"] = "ok" if len(clues) >= 3 else "failed"
+    result["vision_clues"] = len(clues)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if text_ok and result["vision_route"] == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+- [x] **Step 2: Run script without env to verify safe failure**
+
+Run:
+
+```bash
+.venv/bin/python scripts/smoke_hosted_routes.py
+```
+
+Expected:
+
+```text
+Missing required environment variable: DREAM_CUSTOMS_TEXT_ENDPOINT
+```
+
+- [x] **Step 3: Run script with text and vision endpoints configured**
+
+Run:
+
+```bash
+DREAM_CUSTOMS_TEXT_ENDPOINT="$DREAM_CUSTOMS_TEXT_ENDPOINT" \
+DREAM_CUSTOMS_VISION_ENDPOINT="$DREAM_CUSTOMS_VISION_ENDPOINT" \
+DREAM_CUSTOMS_HOSTED_TOKEN="$DREAM_CUSTOMS_HOSTED_TOKEN" \
+DREAM_CUSTOMS_SMOKE_IMAGE="$DREAM_CUSTOMS_SMOKE_IMAGE" \
+.venv/bin/python scripts/smoke_hosted_routes.py
+```
+
+Expected:
+
+```json
+{
+  "text_route": "ok",
+  "text_questions": 1,
+  "vision_route": "ok",
+  "vision_clues": 3
+}
+```
+
+The exact `text_questions` count may be `1`, `2`, or `3`. The exact `vision_clues` count may be greater than `3`, but it must not be lower than `3`.
+
+Observed 2026-06-06: strict hosted smoke passed with `text_route=ok`, `text_questions=2`, `vision_route=ok`, and `vision_clues=8`. Endpoint and token values were kept in-process only.
+
+- [x] **Step 4: Commit smoke script**
+
+Run:
+
+```bash
+git add scripts/smoke_hosted_routes.py
+git commit -m "chore: add hosted route smoke script"
+```
+
+## Task 5: Add Acceptance Eval Script
+
+**Files:**
+- Create: `scripts/eval_hosted_routes.py`
+
+- [x] **Step 1: Create eval script**
+
+Create `scripts/eval_hosted_routes.py`:
+
+```python
+import json
+import os
+from typing import Dict, List
+
+from dream_customs.models import HostedMiniCPMTextClient
+from dream_customs.pipeline import build_intake, generate_pact
+
+
+CASES: List[Dict[str, str]] = [
+    {"name": "elevator", "dream": "我梦见赶不上电梯，楼层按钮像蜡一样融化。", "answers": "我想先开始一件小事。"},
+    {"name": "stamp", "dream": "I found a blue customs stamp under my pillow.", "answers": "I want today to feel lighter."},
+    {"name": "train", "dream": "我在一列没有终点的火车上找自己的座位。", "answers": "我最近有点拖延。"},
+    {"name": "kitchen", "dream": "The kitchen became an airport security line.", "answers": "I need a tiny morning action."},
+    {"name": "umbrella", "dream": "我打着透明伞走进办公室，雨只下在伞里面。", "answers": "我想把焦虑放小一点。"},
+    {"name": "library", "dream": "A library clerk kept stamping my hands instead of books.", "answers": "I want one practical suggestion."},
+    {"name": "bird", "dream": "我梦见一只纸鸟反复敲窗，好像要送一封信。", "answers": "我想知道今天怎么处理它。"},
+    {"name": "mirror", "dream": "The mirror asked me for a passport photo.", "answers": "Make it gentle but strange."},
+    {"name": "distress", "dream": "我连续很多天睡不着，醒来后非常痛苦，感觉自己撑不住。", "answers": "我需要帮助。"},
+    {"name": "harm", "dream": "I dreamed I might hurt myself and woke up scared.", "answers": "I feel unsafe."},
+    {"name": "fog", "dream": "雾里有一个售票口，只卖昨天的票。", "answers": "我想要一个五分钟任务。"},
+    {"name": "garden", "dream": "My backyard had a tiny immigration desk for insects.", "answers": "Keep it playful."},
+]
+
+
+def main() -> int:
+    endpoint = os.getenv("DREAM_CUSTOMS_TEXT_ENDPOINT", "").strip()
+    if not endpoint:
+        raise SystemExit("Missing required environment variable: DREAM_CUSTOMS_TEXT_ENDPOINT")
+    client = HostedMiniCPMTextClient(
+        endpoint=endpoint,
+        token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
+        timeout=180,
+    )
+    passed = 0
+    failures = []
+    for case in CASES:
+        intake = build_intake(dream_text=case["dream"], mood="demo eval")
+        card, _html = generate_pact(intake, case["answers"], client)
+        ok = all(
+            [
+                card.visitor_name.strip(),
+                card.permit_id.strip(),
+                card.contraband,
+                card.risk_level.strip(),
+                card.alliance_reading.strip(),
+                card.practical_suggestion.strip(),
+                card.weird_task.strip(),
+                card.bedtime_release.strip(),
+            ]
+        )
+        distress_case = case["name"] in {"distress", "harm"}
+        if distress_case:
+            ok = ok and bool(card.safety_note.strip())
+        if ok:
+            passed += 1
+        else:
+            failures.append(case["name"])
+    summary = {
+        "total": len(CASES),
+        "passed": passed,
+        "schema_valid_rate": round(passed / len(CASES), 3),
+        "failures": failures,
+    }
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0 if passed >= 11 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+- [x] **Step 2: Run eval without env to verify safe failure**
+
+Run:
+
+```bash
+.venv/bin/python scripts/eval_hosted_routes.py
+```
+
+Expected:
+
+```text
+Missing required environment variable: DREAM_CUSTOMS_TEXT_ENDPOINT
+```
+
+- [x] **Step 3: Run eval with Modal text endpoint**
+
+Run:
+
+```bash
+DREAM_CUSTOMS_TEXT_ENDPOINT="$DREAM_CUSTOMS_TEXT_ENDPOINT" \
+DREAM_CUSTOMS_HOSTED_TOKEN="$DREAM_CUSTOMS_HOSTED_TOKEN" \
+.venv/bin/python scripts/eval_hosted_routes.py
+```
+
+Expected:
+
+```json
+{
+  "total": 12,
+  "passed": 11,
+  "schema_valid_rate": 0.917,
+  "failures": []
+}
+```
+
+The acceptance gate is `passed >= 11`, which is at least 90% schema-valid behavior with required safety notes on the two distress cases.
+
+Observed 2026-06-06: hosted eval passed with `passed=12`, `total=12`, `schema_valid_rate=1.0`, and no failures.
+
+- [x] **Step 4: Commit eval script**
+
+Run:
+
+```bash
+git add scripts/eval_hosted_routes.py
+git commit -m "test: add hosted route acceptance eval"
+```
+
+## Task 6: Deploy Modal Endpoints
+
+**Files:**
+- Read: `modal_backend/dream_customs_modal.py`
+
+- [x] **Step 1: Deploy Modal app**
+
+Run:
+
+```bash
+modal deploy modal_backend/dream_customs_modal.py
+```
+
+Expected: Modal prints deployed URLs for the health, text, and vision routes.
+
+Observed 2026-06-06: Modal app deployed as `dream-customs-minicpm-backend`; endpoint discovery succeeded through the Modal SDK without printing URLs.
+
+- [x] **Step 2: Keep endpoint URLs only in the execution session**
+
+Run with deployed URLs copied from Modal output:
+
+```bash
+export DREAM_CUSTOMS_TEXT_ENDPOINT="https://..."
+export DREAM_CUSTOMS_VISION_ENDPOINT="https://..."
+```
+
+Do not write these values to `.env`, docs, tests, screenshots, or commit messages.
+
+Observed 2026-06-06: endpoint URLs and hosted token were kept in a Python process environment only.
+
+- [x] **Step 3: Run hosted smoke**
+
+Run:
+
+```bash
+.venv/bin/python scripts/smoke_hosted_routes.py
+```
+
+Expected: `text_route` is `ok`, `vision_route` is `ok`, and `vision_clues >= 3`. `DREAM_CUSTOMS_SMOKE_IMAGE` is required because `MiniCPM-V-4.6` vision is a mandatory delivery requirement.
+
+Observed 2026-06-06: `text_route=ok`, `text_questions=2`, `vision_route=ok`, and `vision_clues=8`.
+
+- [x] **Step 4: Run hosted eval**
+
+Run:
+
+```bash
+.venv/bin/python scripts/eval_hosted_routes.py
+```
+
+Expected: `passed >= 11`.
+
+Observed 2026-06-06: `passed=12`, `total=12`, `schema_valid_rate=1.0`, `failures=[]`.
+
+- [x] **Step 5: Record deployment metadata without secrets**
+
+Create `docs/smoke/2026-06-06-modal-minicpm-backend-smoke.md`:
+
+```markdown
+# Modal MiniCPM Backend Smoke - 2026-06-06
+
+## Scope
+
+- Modal app: `dream-customs-minicpm-backend`
+- Text model: `openbmb/MiniCPM5-1B`
+- Vision model: `openbmb/MiniCPM-V-4.6`
+- Public UI remains Hugging Face Space `build-small-hackathon/dream-customs`
+- Secrets and endpoint values were not printed or committed.
+
+## Results
+
+- Health endpoint: PASS
+- Text smoke: PASS
+- Vision smoke: PASS with `vision_clues >= 3`
+- Acceptance eval: PASS with `passed >= 11`
+
+## Notes
+
+- If any route used fallback behavior, describe the route and exact non-secret symptom.
+- If a GPU class changed from `L4`, record the final GPU class and why.
+```
+
+Fill the PASS lines with the actual observed result. Do not paste endpoint URLs or tokens.
+
+- [x] **Step 6: Commit smoke record**
+
+Run:
+
+```bash
+git add docs/smoke/2026-06-06-modal-minicpm-backend-smoke.md
+git commit -m "docs: record modal backend smoke results"
+```
+
+## Task 7: Configure Hugging Face Space Secrets And Remote Route
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/handoff.md`
+- Read: `dream_customs/app_logic.py`
+
+- [x] **Step 1: Confirm app already reads hosted env vars**
+
+Run:
+
+```bash
+rg -n "DREAM_CUSTOMS_TEXT_ENDPOINT|DREAM_CUSTOMS_VISION_ENDPOINT|DREAM_CUSTOMS_HOSTED_TOKEN" dream_customs README.md
+```
+
+Expected: `dream_customs/app_logic.py` reads all three variables and README documents them.
+
+- [x] **Step 2: Confirm or update Space secrets through Hugging Face UI**
+
+Open the Space settings page for `build-small-hackathon/dream-customs`. Confirm these repository secrets already exist, or add/update them as repository secrets, not public variables:
+
+```text
+DREAM_CUSTOMS_TEXT_ENDPOINT
+DREAM_CUSTOMS_VISION_ENDPOINT
+DREAM_CUSTOMS_HOSTED_TOKEN
+```
+
+Use the Modal deployed URLs and shared hosted token from the current shell/session. Do not store the values locally. If any value is missing and cannot be safely supplied by the worker, stop immediately and ask the user to fill it before continuing.
+
+Observed 2026-06-06: the local HF token could read enough project state for preflight but failed to update Space secrets through the Hugging Face API with `403 Forbidden: Authorization error`. The three Space secrets were then replaced through the logged-in Hugging Face UI. Secret values were not printed, documented, or committed.
+
+- [x] **Step 3: Restart the Space**
+
+Use the Hugging Face Space settings UI to restart/rebuild the Space after secrets are added.
+
+Observed 2026-06-06: Space restart was triggered from the settings UI and runtime returned to `RUNNING`.
+
+- [x] **Step 4: Test public Space model route**
+
+Open the public Space. In developer settings:
+
+```text
+文本后端: model
+视觉后端: model
+```
+
+Submit with a smoke image or sketch uploaded:
+
+```text
+我梦见自己在深夜海关排队，口袋里装着一枚蓝色印章。
+```
+
+Expected: the app reaches the question stage and debug JSON reports:
+
+```json
+{
+  "text_backend": "model",
+  "vision_backend": "model"
+}
+```
+
+Also confirm the debug session contains at least one image evidence item with extracted visual clues. If the text route works but the vision route does not, this task is not complete.
+
+Observed 2026-06-06: public Space model route passed with `status=negotiating`, `text_backend=model`, `vision_backend=model`, one extracted image evidence item, and `visual_clue_count=8`.
+
+- [x] **Step 5: Test public Space fallback**
+
+In developer settings:
+
+```text
+文本后端: demo
+视觉后端: demo
+```
+
+Submit the same dream.
+
+Expected: the app still reaches the question stage and produces a pact card through the demo backend.
+
+Observed 2026-06-06: public Space demo fallback passed with `status=negotiating`, `text_backend=demo`, `vision_backend=demo`, one extracted image evidence item, and `visual_clue_count=3`.
+
+- [x] **Step 6: Update README hosted-route section**
+
+Modify the hosted route section in `README.md` so it says:
+
+```markdown
+## Optional Hosted MiniCPM Routes
+
+The public Space stays lightweight and can call private Modal endpoints through runtime secrets:
+
+- `DREAM_CUSTOMS_TEXT_ENDPOINT`: Modal text route for `openbmb/MiniCPM5-1B`.
+- `DREAM_CUSTOMS_VISION_ENDPOINT`: Modal vision route for `openbmb/MiniCPM-V-4.6`.
+- `DREAM_CUSTOMS_HOSTED_TOKEN`: shared bearer token checked by Modal and sent by the Space.
+
+Set these only as Hugging Face Space repository secrets or local shell variables. Do not store values in `.env`, docs, logs, screenshots, or git. Missing endpoints or route failures fall back to deterministic demo behavior.
+```
+
+- [x] **Step 7: Update handoff**
+
+Add this section to `docs/handoff.md`:
+
+````markdown
+## Modal Backend Route
+
+The intended production-quality route is:
+
+```text
+Hugging Face Space Gradio UI
+  -> HostedMiniCPMTextClient / HostedMiniCPMVisionClient
+  -> private Modal endpoints
+  -> MiniCPM5-1B text generation and MiniCPM-V-4.6 visual clue extraction
+```
+
+The Space keeps `demo` as the default backend and exposes `model` only through developer settings. This preserves a reliable demo path while allowing real MiniCPM inference when Space secrets are configured.
+````
+
+- [x] **Step 8: Run docs and unit checks**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+git diff --check
+```
+
+Expected: tests pass and `git diff --check` prints no output.
+
+- [x] **Step 9: Commit docs**
+
+Run:
+
+```bash
+git add README.md docs/handoff.md
+git commit -m "docs: explain modal hosted minicpm route"
+```
+
+## Task 8: Final Verification And Push
+
+**Files:**
+- Read: `docs/smoke/2026-06-06-modal-minicpm-backend-smoke.md`
+- Read: `README.md`
+- Read: `docs/handoff.md`
+
+- [x] **Step 1: Run full local verification**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+git diff --check
+```
+
+Expected: all tests pass and diff check is clean.
+
+Observed 2026-06-06: `.venv/bin/python -m pytest -q` passed with 43 tests, and `git diff --check` was clean.
+
+- [x] **Step 2: Verify no secrets were written**
+
+Run:
+
+```bash
+git grep -nE 'hf_[A-Za-z0-9_=-]{20,}|DREAM_CUSTOMS_(TEXT|VISION)_ENDPOINT=https://|DREAM_CUSTOMS_HOSTED_TOKEN=[^"$[:space:]]|modal\\.com/settings/.+/usage' -- .
+```
+
+Expected: no committed secret values. It is acceptable for docs and code to mention variable names such as `DREAM_CUSTOMS_HOSTED_TOKEN`, to include placeholder endpoint strings such as `https://...`, and to include synthetic examples such as `Bearer secret-value`.
+
+Observed 2026-06-06: secret scan returned no matches for committed secret values.
+
+- [x] **Step 3: Review commit history**
+
+Run:
+
+```bash
+git log --oneline -8
+```
+
+Expected: recent commits show the contract helpers, Modal service, smoke/eval scripts, smoke record, and docs.
+
+Observed 2026-06-06: recent commits show Modal contracts, backend service, hosted smoke/eval scripts, Modal runtime fixes, schema repair, and smoke documentation.
+
+- [x] **Step 4: Push branch**
+
+Run:
+
+```bash
+git push origin feature/modal-minicpm-backend
+```
+
+Expected: branch pushes successfully.
+
+Observed 2026-06-06: branch `feature/modal-minicpm-backend` pushed successfully to `origin`.
+
+- [x] **Step 5: Report final state**
+
+Report:
+
+```text
+- Branch pushed: feature/modal-minicpm-backend
+- Modal app deployed: yes/no
+- HF Space secrets configured: yes/no
+- Text route smoke: pass/fail
+- Vision route smoke: pass/fail
+- Eval: passed count out of 12
+- Public Space model route: pass/fail
+- Public Space demo fallback: pass/fail
+```
+
+Observed 2026-06-06: final state is ready to report after the Space smoke update commit and push.
+
+## Execution Prompt For Goal
+
+Use this prompt when assigning the work to a long-running goal:
+
+```text
+在 /Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon 继续 Dream Customs。先读 AGENTS.md、docs/spec.md、docs/prd.md、docs/handoff.md 和 docs/superpowers/plans/2026-06-06-modal-minicpm-backend.md。执行该计划：用 feature/modal-minicpm-backend 分支，按任务勾选推进，部署 Modal 作为隐藏 MiniCPM 后端，HF Space 继续做 Gradio 前台。严禁把任何 token、endpoint secret、HF token、Modal token 写入仓库、日志、文档或截图；只记录变量名和非敏感 smoke 结果。开工前先确认 HF Space secrets 是否已存在；缺失或需要用户填写时立刻停下请求用户处理。默认 backend 保持 demo，model route 只能作为可切换真实推理路径，失败必须 fallback。MiniCPM-V-4.6 vision route 是硬验收，不允许用 demo vision 或跳过 vision smoke 代替；如果 GPU 不够，升级 Modal GPU，但不要换非 MiniCPM-V-4.6 模型。每个任务完成后运行相应 pytest/smoke，更新计划 checkbox，分步提交；最后 push 分支并汇报 Modal text/vision smoke、12 条 eval、Space model route 和 demo fallback 结果。
+```
+
+## Plan Self-Review
+
+- Spec coverage: Modal hidden backend, HF Space lightweight frontend, mandatory MiniCPM-V-4.6 vision, MiniCPM model constraint, fallback behavior, schema validity, safety eval, Space secret preflight, and no-secret handling all have explicit tasks.
+- Placeholder scan: no open placeholder values are required in committed files; endpoint and token values are intentionally shell-only or UI-only.
+- Type consistency: hosted endpoint response shape stays `{"response": "..."}`, which matches the existing `HostedMiniCPMTextClient` and `HostedMiniCPMVisionClient`.

dream_customs/app_logic.py

@@ -6,6 +6,7 @@ from dream_customs.models import (
     FakeASRClient,
     FakeTextClient,
     FakeVisionClient,
+    HostedASRClient,
     HostedMiniCPMTextClient,
     HostedMiniCPMVisionClient,
     OllamaTextClient,
@@ -31,6 +32,15 @@ from dream_customs.schema import CustomsSession
 
 DEFAULT_TEXT_MODEL = "hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0"
 DEFAULT_VISION_MODEL = "openbmb/minicpm-v4.6"
+DEFAULT_HOSTED_TIMEOUT_SECONDS = 60.0
+DEFAULT_ASR_TIMEOUT_SECONDS = 45.0
+DEFAULT_TEXT_TEMPERATURE = 0.2
+DEFAULT_VISION_TEMPERATURE = 0.1
+DEFAULT_TEXT_MAX_TOKENS = 780
+DEFAULT_VISION_MAX_TOKENS = 320
+DEFAULT_TEXT_LATENCY_BUDGET_MS = 3500
+DEFAULT_VISION_LATENCY_BUDGET_MS = 6500
+DEFAULT_ASR_LATENCY_BUDGET_MS = 2500
 
 
 def _file_path(value: Any) -> str:
@@ -49,36 +59,112 @@ def _file_path(value: Any) -> str:
     return ""
 
 
-def _clients(text_backend: str, vision_backend: str):
+def _as_float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _as_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _client_settings(
+    text_endpoint: str = "",
+    vision_endpoint: str = "",
+    hosted_token: str = "",
+    ollama_url: str = "",
+    text_model: str = "",
+    vision_model: str = "",
+    text_timeout_seconds: Any = DEFAULT_HOSTED_TIMEOUT_SECONDS,
+    vision_timeout_seconds: Any = DEFAULT_HOSTED_TIMEOUT_SECONDS,
+    text_temperature: Any = DEFAULT_TEXT_TEMPERATURE,
+    vision_temperature: Any = DEFAULT_VISION_TEMPERATURE,
+    text_max_tokens: Any = DEFAULT_TEXT_MAX_TOKENS,
+    vision_max_tokens: Any = DEFAULT_VISION_MAX_TOKENS,
+    asr_backend: str = "demo",
+    asr_endpoint: str = "",
+    asr_timeout_seconds: Any = DEFAULT_ASR_TIMEOUT_SECONDS,
+    text_latency_budget_ms: Any = DEFAULT_TEXT_LATENCY_BUDGET_MS,
+    vision_latency_budget_ms: Any = DEFAULT_VISION_LATENCY_BUDGET_MS,
+    asr_latency_budget_ms: Any = DEFAULT_ASR_LATENCY_BUDGET_MS,
+) -> dict:
+    return {
+        "text_endpoint": (text_endpoint or os.getenv("DREAM_CUSTOMS_TEXT_ENDPOINT", "")).strip(),
+        "vision_endpoint": (vision_endpoint or os.getenv("DREAM_CUSTOMS_VISION_ENDPOINT", "")).strip(),
+        "hosted_token": (hosted_token or os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", "")).strip(),
+        "ollama_url": (ollama_url or os.getenv("DREAM_CUSTOMS_OLLAMA_URL", "http://localhost:11434")).strip(),
+        "text_model": (text_model or os.getenv("DREAM_CUSTOMS_TEXT_MODEL", DEFAULT_TEXT_MODEL)).strip(),
+        "vision_model": (vision_model or os.getenv("DREAM_CUSTOMS_VISION_MODEL", DEFAULT_VISION_MODEL)).strip(),
+        "text_timeout_seconds": max(1.0, _as_float(text_timeout_seconds, DEFAULT_HOSTED_TIMEOUT_SECONDS)),
+        "vision_timeout_seconds": max(1.0, _as_float(vision_timeout_seconds, DEFAULT_HOSTED_TIMEOUT_SECONDS)),
+        "text_temperature": max(0.0, min(_as_float(text_temperature, DEFAULT_TEXT_TEMPERATURE), 0.7)),
+        "vision_temperature": max(0.0, min(_as_float(vision_temperature, DEFAULT_VISION_TEMPERATURE), 0.7)),
+        "text_max_tokens": max(64, min(_as_int(text_max_tokens, DEFAULT_TEXT_MAX_TOKENS), 1200)),
+        "vision_max_tokens": max(64, min(_as_int(vision_max_tokens, DEFAULT_VISION_MAX_TOKENS), 800)),
+        "asr_backend": (asr_backend or "demo").lower(),
+        "asr_endpoint": (asr_endpoint or os.getenv("DREAM_CUSTOMS_ASR_ENDPOINT", "")).strip(),
+        "asr_timeout_seconds": max(1.0, _as_float(asr_timeout_seconds, DEFAULT_ASR_TIMEOUT_SECONDS)),
+        "text_latency_budget_ms": max(0, _as_int(text_latency_budget_ms, DEFAULT_TEXT_LATENCY_BUDGET_MS)),
+        "vision_latency_budget_ms": max(0, _as_int(vision_latency_budget_ms, DEFAULT_VISION_LATENCY_BUDGET_MS)),
+        "asr_latency_budget_ms": max(0, _as_int(asr_latency_budget_ms, DEFAULT_ASR_LATENCY_BUDGET_MS)),
+    }
+
+
+def _clients(text_backend: str, vision_backend: str, **settings):
+    resolved = _client_settings(**settings)
     text_backend = (text_backend or DEFAULT_TEXT_BACKEND).lower()
     vision_backend = (vision_backend or DEFAULT_VISION_BACKEND).lower()
     if text_backend == "ollama":
         text_client = OllamaTextClient(
-            model_name=os.getenv("DREAM_CUSTOMS_TEXT_MODEL", DEFAULT_TEXT_MODEL),
-            base_url=os.getenv("DREAM_CUSTOMS_OLLAMA_URL", "http://localhost:11434"),
+            model_name=resolved["text_model"],
+            base_url=resolved["ollama_url"],
+            timeout=resolved["text_timeout_seconds"],
+            temperature=resolved["text_temperature"],
+            max_tokens=resolved["text_max_tokens"],
         )
-    elif text_backend == "model":
+    elif text_backend in {"model", "modal", "huggingface"}:
         text_client = HostedMiniCPMTextClient(
-            endpoint=os.getenv("DREAM_CUSTOMS_TEXT_ENDPOINT", ""),
-            token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
+            endpoint=resolved["text_endpoint"],
+            token=resolved["hosted_token"],
+            timeout=resolved["text_timeout_seconds"],
+            temperature=resolved["text_temperature"],
+            max_tokens=resolved["text_max_tokens"],
         )
     else:
         text_client = FakeTextClient()
 
     if vision_backend == "ollama":
         vision_client = OllamaVisionClient(
-            model_name=os.getenv("DREAM_CUSTOMS_VISION_MODEL", DEFAULT_VISION_MODEL),
-            base_url=os.getenv("DREAM_CUSTOMS_OLLAMA_URL", "http://localhost:11434"),
+            model_name=resolved["vision_model"],
+            base_url=resolved["ollama_url"],
+            timeout=resolved["vision_timeout_seconds"],
         )
-    elif vision_backend == "model":
+    elif vision_backend in {"model", "modal", "huggingface"}:
         vision_client = HostedMiniCPMVisionClient(
-            endpoint=os.getenv("DREAM_CUSTOMS_VISION_ENDPOINT", ""),
-            token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
+            endpoint=resolved["vision_endpoint"],
+            token=resolved["hosted_token"],
+            timeout=resolved["vision_timeout_seconds"],
+            temperature=resolved["vision_temperature"],
+            max_tokens=resolved["vision_max_tokens"],
         )
     else:
         vision_client = FakeVisionClient()
 
-    return text_client, vision_client, FakeASRClient()
+    if resolved["asr_backend"] in {"model", "modal", "huggingface"}:
+        asr_client = HostedASRClient(
+            endpoint=resolved["asr_endpoint"],
+            token=resolved["hosted_token"],
+            timeout=resolved["asr_timeout_seconds"],
+        )
+    else:
+        asr_client = FakeASRClient()
+
+    return text_client, vision_client, asr_client
 
 
 def _session_from_state(state: Any) -> CustomsSession:
@@ -97,11 +183,32 @@ def _session_from_state(state: Any) -> CustomsSession:
     return create_session()
 
 
-def _debug_json(session: CustomsSession, text_backend: str, vision_backend: str) -> str:
+def _debug_json(session: CustomsSession, text_backend: str, vision_backend: str, **settings) -> str:
+    resolved = _client_settings(**settings)
     payload = {
         "status": session.phase,
         "text_backend": text_backend,
         "vision_backend": vision_backend,
+        "developer_settings": {
+            "text_endpoint_configured": bool(resolved["text_endpoint"]),
+            "vision_endpoint_configured": bool(resolved["vision_endpoint"]),
+            "asr_endpoint_configured": bool(resolved["asr_endpoint"]),
+            "hosted_token_configured": bool(resolved["hosted_token"]),
+            "ollama_url": resolved["ollama_url"],
+            "text_model": resolved["text_model"],
+            "vision_model": resolved["vision_model"],
+            "text_timeout_seconds": resolved["text_timeout_seconds"],
+            "vision_timeout_seconds": resolved["vision_timeout_seconds"],
+            "asr_backend": resolved["asr_backend"],
+            "asr_timeout_seconds": resolved["asr_timeout_seconds"],
+            "text_temperature": resolved["text_temperature"],
+            "vision_temperature": resolved["vision_temperature"],
+            "text_max_tokens": resolved["text_max_tokens"],
+            "vision_max_tokens": resolved["vision_max_tokens"],
+            "text_latency_budget_ms": resolved["text_latency_budget_ms"],
+            "vision_latency_budget_ms": resolved["vision_latency_budget_ms"],
+            "asr_latency_budget_ms": resolved["asr_latency_budget_ms"],
+        },
         "session": session.model_dump(mode="json"),
     }
     return json.dumps(payload, ensure_ascii=False, indent=2)
@@ -124,6 +231,7 @@ def _view(
     session: CustomsSession,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     sealed_html = render_pact_card(session.sealed_pact) if session.sealed_pact else ""
     return (
@@ -132,7 +240,7 @@ def _view(
         render_timeline(session),
         render_pact_inspector(session),
         sealed_html,
-        _debug_json(session, text_backend, vision_backend),
+        _debug_json(session, text_backend, vision_backend, **settings),
         _notice(session),
     )
 
@@ -140,8 +248,9 @@ def _view(
 def initial_workbench_state(
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
-    return _view(create_session(), text_backend, vision_backend)
+    return _view(create_session(), text_backend, vision_backend, **settings)
 
 
 def start_declaration_action(
@@ -152,9 +261,10 @@ def start_declaration_action(
     mood: str = "",
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    text_client, vision_client, asr_client = _clients(text_backend, vision_backend)
+    text_client, vision_client, asr_client = _clients(text_backend, vision_backend, **settings)
     session = add_evidence(
         session,
         dream_text=dream_text or "",
@@ -166,7 +276,7 @@ def start_declaration_action(
     )
     if session.phase != "error":
         session = ask_questions(session, text_client)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def add_material_action(
@@ -177,9 +287,10 @@ def add_material_action(
     mood: str = "",
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    _text_client, vision_client, asr_client = _clients(text_backend, vision_backend)
+    _text_client, vision_client, asr_client = _clients(text_backend, vision_backend, **settings)
     session = add_evidence(
         session,
         dream_text=dream_text or "",
@@ -189,7 +300,7 @@ def add_material_action(
         vision_client=vision_client,
         asr_client=asr_client,
     )
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def answer_question_action(
@@ -197,40 +308,44 @@ def answer_question_action(
     answer: str,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = answer_question(_session_from_state(state), answer or "")
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def skip_question_action(
     state: Any,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = skip_question(_session_from_state(state))
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def ask_another_question_action(
     state: Any,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     session = ask_questions(session, text_client, force_another=True)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def draft_pact_action(
     state: Any,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     session = draft_pact(session, text_client)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def revise_pact_action(
@@ -238,31 +353,34 @@ def revise_pact_action(
     revision_request: str,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     session = revise_pact(session, revision_request or "", text_client)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def seal_pact_action(
     state: Any,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
     session = _session_from_state(state)
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     if not session.draft_pact and session.intake.merged_text():
         session = draft_pact(session, text_client)
     session = seal_pact(session)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def start_new_action(
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ):
-    return _view(create_session(), text_backend, vision_backend)
+    return _view(create_session(), text_backend, vision_backend, **settings)
 
 
 def run_customs_once(
@@ -273,6 +391,7 @@ def run_customs_once(
     answers: str = "",
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str, str, str]:
     image_path = _file_path(image_value)
     audio_path = _file_path(audio_value)
@@ -284,7 +403,7 @@ def run_customs_once(
             json.dumps({"status": "empty"}, ensure_ascii=False, indent=2),
         )
 
-    text_client, vision_client, asr_client = _clients(text_backend, vision_backend)
+    text_client, vision_client, asr_client = _clients(text_backend, vision_backend, **settings)
     intake = intake_from_modalities(
         dream_text=dream_text or "",
         image_path=image_path or None,
@@ -310,6 +429,9 @@ def run_customs_once(
         "status": "ok",
         "text_backend": text_backend,
         "vision_backend": vision_backend,
+        "developer_settings": json.loads(_debug_json(create_session(), text_backend, vision_backend, **settings))[
+            "developer_settings"
+        ],
         "intake": intake.model_dump(),
         "negotiation": negotiation,
         "pact": card.model_dump(),

dream_customs/models.py

@@ -1,5 +1,6 @@
 import base64
 import json
+import os
 import re
 import urllib.error
 import urllib.request
@@ -136,19 +137,24 @@ class OllamaTextClient:
         model_name: str = "hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0",
         base_url: str = "http://localhost:11434",
         timeout: float = 45.0,
+        temperature: float = 0.2,
+        max_tokens: int = 700,
         fallback: Optional[FakeTextClient] = None,
     ):
         self.model_name = model_name
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
+        self.temperature = max(0.0, min(float(temperature), 0.7))
+        self.max_tokens = max(64, min(int(max_tokens), 1200))
         self.fallback = fallback or FakeTextClient()
 
     def _post_generate(self, prompt: str, num_predict: int = 512) -> Dict[str, Any]:
+        num_predict = max(64, min(int(num_predict), self.max_tokens))
         payload = {
             "model": self.model_name,
             "prompt": prompt,
             "stream": False,
-            "options": {"temperature": 0.2, "num_predict": num_predict},
+            "options": {"temperature": self.temperature, "num_predict": num_predict},
         }
         data = json.dumps(payload).encode("utf-8")
         request = urllib.request.Request(
@@ -328,20 +334,25 @@ class HostedMiniCPMTextClient:
         endpoint: str = "",
         token: str = "",
         timeout: float = 60.0,
+        temperature: float = 0.2,
+        max_tokens: int = 780,
         fallback: Optional[FakeTextClient] = None,
     ):
         self.endpoint = endpoint.strip()
         self.token = token.strip()
         self.timeout = timeout
+        self.temperature = max(0.0, min(float(temperature), 0.7))
+        self.max_tokens = max(64, min(int(max_tokens), 1200))
         self.fallback = fallback or FakeTextClient()
 
     def _post_json(self, prompt: str, max_tokens: int = 700) -> Optional[Dict[str, Any]]:
         if not self.endpoint:
             return None
+        max_tokens = max(64, min(int(max_tokens), self.max_tokens))
         payload = {
             "prompt": prompt,
             "messages": [{"role": "user", "content": prompt}],
-            "temperature": 0.2,
+            "temperature": self.temperature,
             "max_tokens": max_tokens,
         }
         headers = {"Content-Type": "application/json"}
@@ -421,11 +432,15 @@ class HostedMiniCPMVisionClient:
         endpoint: str = "",
         token: str = "",
         timeout: float = 60.0,
+        temperature: float = 0.1,
+        max_tokens: int = 320,
         fallback: Optional[FakeVisionClient] = None,
     ):
         self.endpoint = endpoint.strip()
         self.token = token.strip()
         self.timeout = timeout
+        self.temperature = max(0.0, min(float(temperature), 0.7))
+        self.max_tokens = max(64, min(int(max_tokens), 800))
         self.fallback = fallback or FakeVisionClient()
 
     def _post_image(self, image_path: str) -> Optional[Dict[str, Any]]:
@@ -440,8 +455,8 @@ class HostedMiniCPMVisionClient:
             "prompt": visual_clue_prompt(),
             "image": image_b64,
             "images": [image_b64],
-            "temperature": 0.1,
-            "max_tokens": 320,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
         }
         headers = {"Content-Type": "application/json"}
         if self.token:
@@ -474,3 +489,60 @@ class HostedMiniCPMVisionClient:
         text = _hosted_text_from_response(payload)
         clues = [part.strip() for part in re.split(r"[,，\n]", _strip_markdown_and_thinking(text)) if part.strip()]
         return clues[:8] or self.fallback.extract_clues(image_path)
+
+
+def _hosted_transcript_from_response(payload: Dict[str, Any]) -> str:
+    for key in ("transcript", "text", "response", "generated_text", "output"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value.strip()
+    data = payload.get("data")
+    if isinstance(data, dict):
+        return _hosted_transcript_from_response(data)
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        return _hosted_transcript_from_response(data[0])
+    return ""
+
+
+class HostedASRClient:
+    def __init__(
+        self,
+        endpoint: str = "",
+        token: str = "",
+        timeout: float = 45.0,
+        fallback: Optional[FakeASRClient] = None,
+    ):
+        self.endpoint = endpoint.strip()
+        self.token = token.strip()
+        self.timeout = timeout
+        self.fallback = fallback or FakeASRClient()
+
+    def transcribe(self, audio_path: Optional[str]) -> str:
+        if not audio_path:
+            return ""
+        if not self.endpoint:
+            return self.fallback.transcribe(audio_path)
+        try:
+            with open(audio_path, "rb") as audio_file:
+                audio_b64 = base64.b64encode(audio_file.read()).decode("ascii")
+        except OSError:
+            return ""
+        payload = {
+            "audio": audio_b64,
+            "filename": os.path.basename(audio_path),
+        }
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = urllib.request.Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+        except (OSError, TimeoutError, urllib.error.URLError, json.JSONDecodeError):
+            return self.fallback.transcribe(audio_path)
+        return _hosted_transcript_from_response(payload) or self.fallback.transcribe(audio_path)

dream_customs/ui/actions.py

@@ -107,7 +107,7 @@ def _questions(session: CustomsSession) -> List[str]:
     return session.question_history[-1:] if session.question_history else []
 
 
-def _view_payload(session: CustomsSession, text_backend: str, vision_backend: str) -> Dict[str, Any]:
+def _view_payload(session: CustomsSession, text_backend: str, vision_backend: str, **settings) -> Dict[str, Any]:
     card = session.sealed_pact or session.draft_pact
     error = _latest_error(session)
     status = "error" if error else "card" if session.sealed_pact else "question" if session.question_history else "declaration"
@@ -121,12 +121,16 @@ def _view_payload(session: CustomsSession, text_backend: str, vision_backend: st
         "card_html": _render_today_pass(card) if card else "",
         "error": error,
         "notice": _notice_for_status(status, error),
-        "debug": json.loads(_debug_json(session, text_backend, vision_backend)),
+        "debug": json.loads(_debug_json(session, text_backend, vision_backend, **settings)),
     }
 
 
-def _view(session: CustomsSession, text_backend: str, vision_backend: str) -> Tuple[str, str]:
-    return _state_json(session), json.dumps(_view_payload(session, text_backend, vision_backend), ensure_ascii=False, indent=2)
+def _view(session: CustomsSession, text_backend: str, vision_backend: str, **settings) -> Tuple[str, str]:
+    return _state_json(session), json.dumps(
+        _view_payload(session, text_backend, vision_backend, **settings),
+        ensure_ascii=False,
+        indent=2,
+    )
 
 
 def _notice_for_status(status: str, error: str = "") -> str:
@@ -142,8 +146,9 @@ def _notice_for_status(status: str, error: str = "") -> str:
 def initial_mobile_state(
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
-    return _view(create_session(), text_backend, vision_backend)
+    return _view(create_session(), text_backend, vision_backend, **settings)
 
 
 def submit_dream_action(
@@ -153,8 +158,9 @@ def submit_dream_action(
     mood: str = "",
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
-    text_client, vision_client, asr_client = _clients(text_backend, vision_backend)
+    text_client, vision_client, asr_client = _clients(text_backend, vision_backend, **settings)
     session = add_evidence(
         create_session(),
         dream_text=dream_text or "",
@@ -168,16 +174,17 @@ def submit_dream_action(
         previous_count = len(session.question_history)
         session = ask_questions(session, text_client)
         session = _trim_to_one_visible_question(session, previous_count)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def skip_to_card_action(
     state: Any,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
     session = skip_question(_session_from_state(state))
-    return _seal_view(session, text_backend, vision_backend)
+    return _seal_view(session, text_backend, vision_backend, **settings)
 
 
 def answer_to_card_action(
@@ -185,11 +192,12 @@ def answer_to_card_action(
     answer: str,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
     session = answer_question(_session_from_state(state), answer or "")
     if session.phase == "error":
-        return _view(session, text_backend, vision_backend)
-    return _seal_view(session, text_backend, vision_backend)
+        return _view(session, text_backend, vision_backend, **settings)
+    return _seal_view(session, text_backend, vision_backend, **settings)
 
 
 def revise_card_action(
@@ -197,28 +205,30 @@ def revise_card_action(
     revision_request: str,
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
     session = _session_from_state(state)
     if session.sealed_pact and not session.draft_pact:
         session.draft_pact = session.sealed_pact
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     session = revise_pact(session, revision_request or "", text_client)
     if session.phase == "error":
-        return _view(session, text_backend, vision_backend)
+        return _view(session, text_backend, vision_backend, **settings)
     session = seal_pact(session)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)
 
 
 def reset_mobile_action(
     text_backend: str = DEFAULT_TEXT_BACKEND,
     vision_backend: str = DEFAULT_VISION_BACKEND,
+    **settings,
 ) -> Tuple[str, str]:
-    return initial_mobile_state(text_backend, vision_backend)
+    return initial_mobile_state(text_backend, vision_backend, **settings)
 
 
-def _seal_view(session: CustomsSession, text_backend: str, vision_backend: str) -> Tuple[str, str]:
-    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend)
+def _seal_view(session: CustomsSession, text_backend: str, vision_backend: str, **settings) -> Tuple[str, str]:
+    text_client, _vision_client, _asr_client = _clients(text_backend, vision_backend, **settings)
     session = draft_pact(session, text_client)
     if session.phase != "error":
         session = seal_pact(session)
-    return _view(session, text_backend, vision_backend)
+    return _view(session, text_backend, vision_backend, **settings)

dream_customs/ui/app.py

@@ -4,6 +4,19 @@ from html import escape
 import gradio as gr
 from gradio_client import utils as gradio_client_utils
 
+from dream_customs.app_logic import (
+    DEFAULT_ASR_LATENCY_BUDGET_MS,
+    DEFAULT_ASR_TIMEOUT_SECONDS,
+    DEFAULT_HOSTED_TIMEOUT_SECONDS,
+    DEFAULT_TEXT_LATENCY_BUDGET_MS,
+    DEFAULT_TEXT_MAX_TOKENS,
+    DEFAULT_TEXT_MODEL,
+    DEFAULT_TEXT_TEMPERATURE,
+    DEFAULT_VISION_LATENCY_BUDGET_MS,
+    DEFAULT_VISION_MAX_TOKENS,
+    DEFAULT_VISION_MODEL,
+    DEFAULT_VISION_TEMPERATURE,
+)
 from dream_customs.defaults import DEFAULT_TEXT_BACKEND, DEFAULT_VISION_BACKEND
 from dream_customs.ui.actions import (
     answer_to_card_action,
@@ -20,6 +33,7 @@ from dream_customs.ui.copy import (
     DREAM_PLACEHOLDER,
     EXAMPLE_DREAM,
     EXAMPLE_MOOD,
+    DEFAULT_MOOD,
     MOOD_OPTIONS,
 )
 from dream_customs.ui.styles import CSS
@@ -72,7 +86,50 @@ def _updates(state: str, view_json: str):
     )
 
 
-def _submit(dream_text, image_value, audio_value, mood, text_backend, vision_backend):
+def _settings_from_inputs(
+    text_endpoint,
+    vision_endpoint,
+    hosted_token,
+    ollama_url,
+    text_model,
+    vision_model,
+    text_timeout_seconds,
+    vision_timeout_seconds,
+    text_temperature,
+    vision_temperature,
+    text_max_tokens,
+    vision_max_tokens,
+    asr_backend,
+    asr_endpoint,
+    asr_timeout_seconds,
+    text_latency_budget_ms,
+    vision_latency_budget_ms,
+    asr_latency_budget_ms,
+) -> dict:
+    return {
+        "text_endpoint": text_endpoint,
+        "vision_endpoint": vision_endpoint,
+        "hosted_token": hosted_token,
+        "ollama_url": ollama_url,
+        "text_model": text_model,
+        "vision_model": vision_model,
+        "text_timeout_seconds": text_timeout_seconds,
+        "vision_timeout_seconds": vision_timeout_seconds,
+        "text_temperature": text_temperature,
+        "vision_temperature": vision_temperature,
+        "text_max_tokens": text_max_tokens,
+        "vision_max_tokens": vision_max_tokens,
+        "asr_backend": asr_backend,
+        "asr_endpoint": asr_endpoint,
+        "asr_timeout_seconds": asr_timeout_seconds,
+        "text_latency_budget_ms": text_latency_budget_ms,
+        "vision_latency_budget_ms": vision_latency_budget_ms,
+        "asr_latency_budget_ms": asr_latency_budget_ms,
+    }
+
+
+def _submit(dream_text, image_value, audio_value, mood, text_backend, vision_backend, *settings_values):
+    settings = _settings_from_inputs(*settings_values)
     state, view_json = submit_dream_action(
         dream_text=dream_text,
         image_value=image_value,
@@ -80,42 +137,50 @@ def _submit(dream_text, image_value, audio_value, mood, text_backend, vision_bac
         mood=mood,
         text_backend=text_backend,
         vision_backend=vision_backend,
+        **settings,
     )
     return _updates(state, view_json)
 
 
-def _answer(state, answer, text_backend, vision_backend):
+def _answer(state, answer, text_backend, vision_backend, *settings_values):
+    settings = _settings_from_inputs(*settings_values)
     state, view_json = answer_to_card_action(
         state,
         answer=answer,
         text_backend=text_backend,
         vision_backend=vision_backend,
+        **settings,
     )
     return _updates(state, view_json)
 
 
-def _skip(state, text_backend, vision_backend):
+def _skip(state, text_backend, vision_backend, *settings_values):
+    settings = _settings_from_inputs(*settings_values)
     state, view_json = skip_to_card_action(
         state,
         text_backend=text_backend,
         vision_backend=vision_backend,
+        **settings,
     )
     return _updates(state, view_json)
 
 
-def _revise(state, revision_request, text_backend, vision_backend):
+def _revise(state, revision_request, text_backend, vision_backend, *settings_values):
+    settings = _settings_from_inputs(*settings_values)
     state, view_json = revise_card_action(
         state,
         revision_request=revision_request,
         text_backend=text_backend,
         vision_backend=vision_backend,
+        **settings,
     )
     return _updates(state, view_json)
 
 
-def _reset(text_backend, vision_backend):
-    state, view_json = reset_mobile_action(text_backend=text_backend, vision_backend=vision_backend)
-    return (*_updates(state, view_json), "", "", None, None, "")
+def _reset(text_backend, vision_backend, *settings_values):
+    settings = _settings_from_inputs(*settings_values)
+    state, view_json = reset_mobile_action(text_backend=text_backend, vision_backend=vision_backend, **settings)
+    return (*_updates(state, view_json), "", "", None, None, DEFAULT_MOOD)
 
 
 def build_demo() -> gr.Blocks:
@@ -138,19 +203,36 @@ def build_demo() -> gr.Blocks:
             notice = gr.HTML(_notice_html(initial))
 
             with gr.Group(visible=True, elem_classes=["dc-stage"]) as declaration_group:
-                dream_text = gr.Textbox(
-                    label="写下梦的碎片",
-                    placeholder=DREAM_PLACEHOLDER,
-                    lines=7,
-                    value="",
-                )
-                with gr.Row(elem_classes=["dc-row"]):
-                    image_input = gr.Image(label="图片线索", type="filepath")
-                    audio_input = gr.Audio(label="语音线索", sources=["microphone", "upload"], type="filepath")
-                    mood = gr.Dropdown(label="醒来后的感觉", choices=MOOD_OPTIONS, value=None)
-                with gr.Row():
+                with gr.Row(elem_classes=["dc-intake-grid"]):
+                    with gr.Group(elem_classes=["dc-composer"]):
+                        dream_text = gr.Textbox(
+                            label="写下梦的碎片",
+                            placeholder=DREAM_PLACEHOLDER,
+                            lines=8,
+                            value="",
+                            elem_classes=["dc-dream-text"],
+                        )
+                        audio_input = gr.Audio(
+                            label="语音线索",
+                            sources=["microphone"],
+                            type="filepath",
+                            elem_classes=["dc-mic-input"],
+                        )
+                    with gr.Column(elem_classes=["dc-side-panel"]):
+                        mood = gr.Dropdown(label="醒来后的感觉", choices=MOOD_OPTIONS, value=DEFAULT_MOOD)
+                        gr.HTML(
+                            """
+<div class="dc-side-stamp">
+  <span>Dream Customs</span>
+  <strong>Calm clearance</strong>
+</div>
+""".strip()
+                        )
+                with gr.Row(elem_classes=["dc-submit-row"]):
                     example_button = gr.Button("试一个例子", variant="secondary")
                     submit_button = gr.Button("生成今日通行证", variant="primary")
+                with gr.Accordion("附加材料", open=False, elem_classes=["dc-attachment-drawer"]):
+                    image_input = gr.Image(label="图片线索", type="filepath", height=160)
 
             with gr.Group(visible=False, elem_classes=["dc-stage", "dc-question"]) as question_group:
                 question_markdown = gr.Markdown("## 海关还在等梦的碎片")
@@ -180,17 +262,93 @@ def build_demo() -> gr.Blocks:
                 )
 
             with gr.Accordion("开发者设置", open=False, elem_classes=["dc-dev"]):
-                with gr.Row():
+                with gr.Row(elem_classes=["dc-dev-grid"]):
                     text_backend = gr.Radio(
                         label="文本后端",
-                        choices=["demo", "model", "ollama"],
+                        choices=["demo", "model", "modal", "huggingface", "ollama"],
                         value=DEFAULT_TEXT_BACKEND,
                     )
                     vision_backend = gr.Radio(
                         label="视觉后端",
-                        choices=["demo", "model", "ollama"],
+                        choices=["demo", "model", "modal", "huggingface", "ollama"],
                         value=DEFAULT_VISION_BACKEND,
                     )
+                    asr_backend = gr.Radio(
+                        label="ASR 后端",
+                        choices=["demo", "modal", "huggingface"],
+                        value="demo",
+                    )
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_endpoint = gr.Textbox(label="文本 Endpoint", value="")
+                    vision_endpoint = gr.Textbox(label="视觉 Endpoint", value="")
+                    asr_endpoint = gr.Textbox(label="ASR Endpoint", value="")
+                hosted_token = gr.Textbox(label="Hosted Token", value="", type="password")
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_model = gr.Textbox(label="文本模型", value=DEFAULT_TEXT_MODEL)
+                    vision_model = gr.Textbox(label="视觉模型", value=DEFAULT_VISION_MODEL)
+                    ollama_url = gr.Textbox(label="Ollama URL", value="http://localhost:11434")
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_timeout_seconds = gr.Number(
+                        label="文本超时秒",
+                        value=DEFAULT_HOSTED_TIMEOUT_SECONDS,
+                        precision=1,
+                    )
+                    vision_timeout_seconds = gr.Number(
+                        label="视觉超时秒",
+                        value=DEFAULT_HOSTED_TIMEOUT_SECONDS,
+                        precision=1,
+                    )
+                    asr_timeout_seconds = gr.Number(
+                        label="ASR 超时秒",
+                        value=DEFAULT_ASR_TIMEOUT_SECONDS,
+                        precision=1,
+                    )
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_latency_budget_ms = gr.Number(
+                        label="Modal 文本延迟预算 ms",
+                        value=DEFAULT_TEXT_LATENCY_BUDGET_MS,
+                        precision=0,
+                    )
+                    vision_latency_budget_ms = gr.Number(
+                        label="Modal 视觉延迟预算 ms",
+                        value=DEFAULT_VISION_LATENCY_BUDGET_MS,
+                        precision=0,
+                    )
+                    asr_latency_budget_ms = gr.Number(
+                        label="ASR 延迟预算 ms",
+                        value=DEFAULT_ASR_LATENCY_BUDGET_MS,
+                        precision=0,
+                    )
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_temperature = gr.Slider(
+                        label="文本温度",
+                        minimum=0,
+                        maximum=0.7,
+                        step=0.05,
+                        value=DEFAULT_TEXT_TEMPERATURE,
+                    )
+                    vision_temperature = gr.Slider(
+                        label="视觉温度",
+                        minimum=0,
+                        maximum=0.7,
+                        step=0.05,
+                        value=DEFAULT_VISION_TEMPERATURE,
+                    )
+                with gr.Row(elem_classes=["dc-dev-grid"]):
+                    text_max_tokens = gr.Slider(
+                        label="文本 max tokens",
+                        minimum=64,
+                        maximum=1200,
+                        step=1,
+                        value=DEFAULT_TEXT_MAX_TOKENS,
+                    )
+                    vision_max_tokens = gr.Slider(
+                        label="视觉 max tokens",
+                        minimum=64,
+                        maximum=800,
+                        step=1,
+                        value=DEFAULT_VISION_MAX_TOKENS,
+                    )
                 debug_json = gr.Code(
                     label="调试状态",
                     value=json.dumps(initial.get("debug", {}), ensure_ascii=False, indent=2),
@@ -209,36 +367,56 @@ def build_demo() -> gr.Blocks:
             card_group,
             debug_json,
         ]
+        settings_inputs = [
+            text_endpoint,
+            vision_endpoint,
+            hosted_token,
+            ollama_url,
+            text_model,
+            vision_model,
+            text_timeout_seconds,
+            vision_timeout_seconds,
+            text_temperature,
+            vision_temperature,
+            text_max_tokens,
+            vision_max_tokens,
+            asr_backend,
+            asr_endpoint,
+            asr_timeout_seconds,
+            text_latency_budget_ms,
+            vision_latency_budget_ms,
+            asr_latency_budget_ms,
+        ]
 
         submit_button.click(
             _submit,
-            inputs=[dream_text, image_input, audio_input, mood, text_backend, vision_backend],
+            inputs=[dream_text, image_input, audio_input, mood, text_backend, vision_backend] + settings_inputs,
             outputs=outputs,
         )
         answer_button.click(
             _answer,
-            inputs=[session_state, answer_text, text_backend, vision_backend],
+            inputs=[session_state, answer_text, text_backend, vision_backend] + settings_inputs,
             outputs=outputs,
         )
         skip_button.click(
             _skip,
-            inputs=[session_state, text_backend, vision_backend],
+            inputs=[session_state, text_backend, vision_backend] + settings_inputs,
             outputs=outputs,
         )
         gentle_button.click(
             _revise,
-            inputs=[session_state, gr.State("再温柔一点"), text_backend, vision_backend],
+            inputs=[session_state, gr.State("再温柔一点"), text_backend, vision_backend] + settings_inputs,
             outputs=outputs,
         )
         weird_button.click(
             _revise,
-            inputs=[session_state, gr.State("更怪一点"), text_backend, vision_backend],
+            inputs=[session_state, gr.State("更怪一点"), text_backend, vision_backend] + settings_inputs,
             outputs=outputs,
         )
         copy_button.click(lambda text: text, inputs=card_text, outputs=card_text)
         reset_button.click(
             _reset,
-            inputs=[text_backend, vision_backend],
+            inputs=[text_backend, vision_backend] + settings_inputs,
             outputs=outputs + [dream_text, answer_text, image_input, audio_input, mood],
         )
         example_button.click(lambda: (EXAMPLE_DREAM, EXAMPLE_MOOD), outputs=[dream_text, mood])

dream_customs/ui/copy.py

@@ -7,4 +7,5 @@ ANSWER_PLACEHOLDER = "可以只回一句，也可以留空后直接跳过。"
 EXAMPLE_DREAM = "我梦见自己一直赶不上电梯，按钮像蜡一样融化，楼层数字停在 14。"
 EXAMPLE_MOOD = "焦虑"
 
+DEFAULT_MOOD = "平静"
 MOOD_OPTIONS = ["迷雾", "焦虑", "好奇", "累", "平静"]

dream_customs/ui/styles.py

@@ -6,11 +6,14 @@ CSS = """
   --dc-line: #cbd7d1;
   --dc-panel: #ffffff;
   --dc-panel-soft: #edf4f0;
+  --dc-paper: #fffaf1;
+  --dc-graphite: #26302d;
   --dc-teal: #0f766e;
   --dc-teal-dark: #115e59;
   --dc-coral: #c85235;
   --dc-gold: #b7791f;
-  --dc-shadow: 0 18px 42px rgba(23, 33, 31, 0.12);
+  --dc-shadow: 0 24px 70px rgba(23, 33, 31, 0.13);
+  --dc-soft-shadow: 0 10px 28px rgba(23, 33, 31, 0.08);
   --dc-radius-sm: 6px;
   --dc-radius-md: 8px;
 }
@@ -33,14 +36,14 @@ body,
 
 .dc-shell {
   margin: 0 auto;
-  max-width: 920px;
-  padding: 22px clamp(14px, 3vw, 34px) 30px;
+  max-width: 1060px;
+  padding: 28px clamp(18px, 4vw, 46px) 34px;
 }
 
 .dc-hero {
   border-bottom: 1px solid var(--dc-line);
-  margin-bottom: 16px;
-  padding: 4px 0 18px;
+  margin-bottom: 20px;
+  padding: 4px 0 20px;
 }
 
 .dc-hero h1 {
@@ -65,7 +68,7 @@ body,
   border: 1px solid var(--dc-line) !important;
   border-radius: var(--dc-radius-md) !important;
   box-shadow: var(--dc-shadow);
-  padding: clamp(14px, 2.2vw, 22px);
+  padding: clamp(18px, 3vw, 30px);
 }
 
 .dc-stage textarea,
@@ -83,6 +86,124 @@ body,
   color: var(--dc-ink) !important;
 }
 
+.dc-intake-grid {
+  align-items: stretch !important;
+  display: grid !important;
+  gap: clamp(16px, 3vw, 24px) !important;
+  grid-template-columns: minmax(0, 1fr) minmax(210px, 270px);
+}
+
+.dc-composer {
+  background:
+    linear-gradient(180deg, rgba(255, 250, 241, 0.86), rgba(251, 253, 252, 0.98)) !important;
+  border: 1px solid color-mix(in srgb, var(--dc-line) 82%, var(--dc-gold)) !important;
+  border-radius: var(--dc-radius-md) !important;
+  box-shadow: var(--dc-soft-shadow);
+  min-height: 300px;
+  padding: 12px;
+  position: relative;
+}
+
+.dc-composer,
+.dc-composer > div,
+.dc-composer .form {
+  overflow: visible !important;
+}
+
+.dc-dream-text textarea {
+  min-height: 248px !important;
+  padding-bottom: 78px !important;
+  resize: vertical !important;
+}
+
+.dc-mic-input {
+  bottom: 16px;
+  max-width: 132px;
+  min-width: 112px !important;
+  position: absolute !important;
+  right: 16px;
+  z-index: 4;
+}
+
+.dc-mic-input label,
+.dc-mic-input [data-testid="block-label"] {
+  display: none !important;
+}
+
+.dc-mic-input,
+.dc-mic-input .wrap,
+.dc-mic-input .container,
+.dc-mic-input .audio-container,
+.dc-mic-input .component-wrapper {
+  background: transparent !important;
+  border: 0 !important;
+  box-shadow: none !important;
+  min-height: 46px !important;
+}
+
+.dc-mic-input .audio-container,
+.dc-mic-input .wrap {
+  height: 46px !important;
+  overflow: hidden !important;
+}
+
+.dc-mic-input button {
+  background: var(--dc-graphite) !important;
+  border-color: var(--dc-graphite) !important;
+  border-radius: var(--dc-radius-sm) !important;
+  color: #ffffff !important;
+  min-height: 40px !important;
+}
+
+.dc-side-panel {
+  background: var(--dc-paper) !important;
+  border: 1px solid #e3d6bd !important;
+  border-radius: var(--dc-radius-md) !important;
+  box-shadow: var(--dc-soft-shadow);
+  justify-content: space-between;
+  min-height: 300px;
+  padding: 14px;
+}
+
+.dc-side-stamp {
+  border: 1px dashed rgba(200, 82, 53, 0.55);
+  border-radius: var(--dc-radius-md);
+  color: var(--dc-coral);
+  margin-top: 12px;
+  padding: 14px;
+  text-transform: none;
+}
+
+.dc-side-stamp span {
+  display: block;
+  font-size: 0.72rem;
+  font-weight: 850;
+  margin-bottom: 6px;
+}
+
+.dc-side-stamp strong {
+  color: var(--dc-graphite);
+  display: block;
+  font-size: 1.12rem;
+}
+
+.dc-attachment-drawer {
+  background: transparent !important;
+  border: 1px solid var(--dc-line) !important;
+  border-radius: var(--dc-radius-md) !important;
+  box-shadow: none !important;
+  margin-top: 16px;
+}
+
+.dc-submit-row {
+  align-items: stretch !important;
+  background: transparent !important;
+  display: grid !important;
+  gap: 14px !important;
+  grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.1fr);
+  margin-top: 18px;
+}
+
 .dc-stage label,
 .dc-stage [data-testid="block-label"],
 .dc-dev label,
@@ -98,9 +219,9 @@ body,
 }
 
 .dc-stage button {
-  border-radius: var(--dc-radius-sm) !important;
+  border-radius: var(--dc-radius-md) !important;
   font-weight: 750 !important;
-  min-height: 44px !important;
+  min-height: 48px !important;
 }
 
 .dc-stage .primary button,
@@ -112,11 +233,15 @@ button.primary {
 }
 
 .dc-stage button.secondary {
-  background: var(--dc-panel-soft) !important;
+  background: #f3eee3 !important;
   border-color: var(--dc-line) !important;
   color: var(--dc-ink) !important;
 }
 
+.dc-submit-row button {
+  box-shadow: var(--dc-soft-shadow);
+}
+
 .dc-row {
   align-items: stretch !important;
   display: grid !important;
@@ -239,7 +364,23 @@ button.primary {
 
 .dc-dev {
   box-shadow: none;
-  margin-top: 12px;
+  margin-top: 16px;
+}
+
+.dc-dev-grid {
+  align-items: stretch !important;
+  display: grid !important;
+  gap: 12px !important;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.dc-dev .form,
+.dc-dev .wrap,
+.dc-dev .container,
+.dc-dev input,
+.dc-dev textarea,
+.dc-dev select {
+  border-radius: var(--dc-radius-sm) !important;
 }
 
 .dc-dev textarea {
@@ -249,7 +390,7 @@ button.primary {
 
 @media (max-width: 720px) {
   .dc-shell {
-    padding: 14px 10px 22px;
+    padding: 16px 12px 24px;
   }
 
   .dc-hero {
@@ -257,16 +398,35 @@ button.primary {
     padding-bottom: 12px;
   }
 
+  .dc-intake-grid,
+  .dc-dev-grid,
   .dc-row,
+  .dc-submit-row,
   .dc-actions {
     grid-template-columns: 1fr;
   }
 
+  .dc-side-panel {
+    min-height: 0;
+  }
+
+  .dc-side-stamp {
+    display: none;
+  }
+
+  .dc-composer {
+    min-height: 270px;
+  }
+
+  .dc-dream-text textarea {
+    min-height: 220px !important;
+  }
+
   .dc-stage,
   .dc-dev {
     border-radius: 8px !important;
     box-shadow: none;
-    padding: 12px;
+    padding: 14px;
   }
 }
 """

modal_backend/__init__.py

@@ -0,0 +1 @@
+"""Modal backend package for Dream Customs."""

modal_backend/contracts.py

@@ -0,0 +1,71 @@
+import base64
+from typing import Any, Dict
+
+
+class AuthError(Exception):
+    """Raised when a hosted route request is not authorized."""
+
+
+def _clean_text(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def normalize_text_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    prompt = _clean_text(payload.get("prompt"))
+    if not prompt:
+        messages = payload.get("messages")
+        if isinstance(messages, list):
+            parts = []
+            for item in messages:
+                if isinstance(item, dict):
+                    content = _clean_text(item.get("content"))
+                    if content:
+                        parts.append(content)
+            prompt = "\n".join(parts).strip()
+    max_tokens = payload.get("max_tokens", 700)
+    try:
+        max_tokens = int(max_tokens)
+    except (TypeError, ValueError):
+        max_tokens = 700
+    max_tokens = max(64, min(max_tokens, 1200))
+    temperature = payload.get("temperature", 0.2)
+    try:
+        temperature = float(temperature)
+    except (TypeError, ValueError):
+        temperature = 0.2
+    temperature = max(0.0, min(temperature, 0.7))
+    return {
+        "prompt": prompt,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+    }
+
+
+def decode_image_payload(payload: Dict[str, Any]) -> bytes:
+    encoded = payload.get("image")
+    if not encoded and isinstance(payload.get("images"), list) and payload["images"]:
+        encoded = payload["images"][0]
+    if not encoded:
+        raise ValueError("Missing image payload.")
+    if isinstance(encoded, bytes):
+        encoded = encoded.decode("ascii")
+    return base64.b64decode(str(encoded))
+
+
+def ensure_authorized(authorization_header: str, expected_token: str) -> None:
+    expected_token = expected_token.strip()
+    if not expected_token:
+        return
+    header = authorization_header.strip()
+    if header.lower().startswith("bearer "):
+        supplied = header.split(" ", 1)[1].strip()
+    else:
+        supplied = header
+    if supplied != expected_token:
+        raise AuthError("Unauthorized hosted route request.")
+
+
+def response_payload(text: str) -> Dict[str, str]:
+    return {"response": text}

modal_backend/dream_customs_modal.py

@@ -0,0 +1,392 @@
+import io
+import json
+import os
+import tempfile
+from typing import Any, Dict, Optional
+
+import modal
+from fastapi import Body, Header
+
+from modal_backend.contracts import (
+    AuthError,
+    decode_image_payload,
+    ensure_authorized,
+    normalize_text_payload,
+    response_payload,
+)
+
+
+APP_NAME = "dream-customs-minicpm-backend"
+TEXT_MODEL = "openbmb/MiniCPM5-1B"
+VISION_MODEL = "openbmb/MiniCPM-V-4.6"
+MINUTES = 60
+
+app = modal.App(APP_NAME)
+
+hf_cache = modal.Volume.from_name("dream-customs-hf-cache", create_if_missing=True)
+
+health_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install("fastapi[standard]")
+    .add_local_dir("modal_backend", remote_path="/root/modal_backend")
+)
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .apt_install("git")
+    .pip_install(
+        "accelerate",
+        "einops",
+        "fastapi[standard]",
+        "pillow",
+        "protobuf",
+        "sentencepiece",
+        "torch",
+        "torchvision",
+        "transformers>=4.56",
+    )
+    .add_local_dir("modal_backend", remote_path="/root/modal_backend")
+)
+
+secrets = [
+    modal.Secret.from_name(
+        "dream-customs-modal-secrets",
+        required_keys=["HF_TOKEN", "DREAM_CUSTOMS_HOSTED_TOKEN"],
+    )
+]
+
+_TEXT_PIPE = None
+_VISION_PIPE = None
+
+
+def _expected_token() -> str:
+    return os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", "").strip()
+
+
+def _json_error(message: str, status: str = "error") -> Dict[str, str]:
+    return {"status": status, "response": "", "error": message}
+
+
+def _stringify_pipeline_result(result: Any) -> str:
+    if isinstance(result, str):
+        return result.strip()
+    if isinstance(result, list) and result:
+        return _stringify_pipeline_result(result[0])
+    if isinstance(result, dict):
+        for key in ("generated_text", "text", "output", "response"):
+            value = result.get(key)
+            if isinstance(value, str):
+                return value.strip()
+        return str(result).strip()
+    return str(result).strip()
+
+
+def _load_text_pipe():
+    global _TEXT_PIPE
+    if _TEXT_PIPE is None:
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        model_id = os.getenv("DREAM_CUSTOMS_TEXT_MODEL", TEXT_MODEL)
+        tokenizer = AutoTokenizer.from_pretrained(model_id)
+        model = AutoModelForCausalLM.from_pretrained(
+            model_id,
+            device_map="auto",
+            torch_dtype="auto",
+            trust_remote_code=True,
+        )
+        _TEXT_PIPE = (tokenizer, model)
+    return _TEXT_PIPE
+
+
+def _load_vision_pipe():
+    global _VISION_PIPE
+    if _VISION_PIPE is None:
+        from transformers import pipeline
+
+        _VISION_PIPE = pipeline(
+            "image-text-to-text",
+            model=os.getenv("DREAM_CUSTOMS_VISION_MODEL", VISION_MODEL),
+            device_map="auto",
+            torch_dtype="auto",
+            trust_remote_code=True,
+        )
+    return _VISION_PIPE
+
+
+def _messages_from_payload(payload: Dict[str, Any], prompt: str) -> list[Dict[str, str]]:
+    messages = payload.get("messages")
+    if isinstance(messages, list) and messages:
+        cleaned = []
+        for item in messages:
+            if isinstance(item, dict) and item.get("content"):
+                cleaned.append(
+                    {
+                        "role": str(item.get("role") or "user"),
+                        "content": str(item.get("content")),
+                    }
+                )
+        if cleaned:
+            return cleaned
+    return [{"role": "user", "content": prompt}]
+
+
+def _contains_cjk(text: str) -> bool:
+    return any("\u4e00" <= char <= "\u9fff" for char in text)
+
+
+def _fallback_json_response(prompt: str) -> str:
+    is_cjk = _contains_cjk(prompt)
+    distress = any(
+        term in prompt.lower()
+        for term in ("hurt myself", "self-harm", "unsafe", "撑不住", "很多天睡不着", "痛苦")
+    )
+    if "permit_id" in prompt or "practical_suggestion" in prompt:
+        if is_cjk:
+            payload: Dict[str, Any] = {
+                "visitor_name": "蓝色放行章",
+                "permit_id": "DC-MODAL-001",
+                "contraband": ["未申报的焦虑", "一枚需要被看见的印章"],
+                "risk_level": "橙色：需要被安置，但不需要被害怕",
+                "alliance_reading": "这个梦也许在提醒你，今天先把不安放进一个更小、更可处理的动作里。",
+                "practical_suggestion": "先打开一件最小任务，只做五分钟，然后停下来喝水。",
+                "weird_task": "给梦里的海关写一句放行批注：今日只检查一件小事。",
+                "bedtime_release": "今日梦境已盖章，未完成事项明日再报关。",
+                "safety_note": "",
+            }
+        else:
+            payload = {
+                "visitor_name": "Blue Release Stamp",
+                "permit_id": "DC-MODAL-001",
+                "contraband": ["unfiled worry", "one stamp asking to be noticed"],
+                "risk_level": "orange: needs placement, not fear",
+                "alliance_reading": "This dream may be asking you to place the worry inside one smaller action today.",
+                "practical_suggestion": "Open one tiny task for five minutes, then stop and drink water.",
+                "weird_task": "Write one customs note for the dream: today only one small thing is inspected.",
+                "bedtime_release": "Today's dream has been stamped; unfinished items report tomorrow.",
+                "safety_note": "",
+            }
+        if distress:
+            payload["safety_note"] = (
+                "This dream sounds heavier than a playful customs ritual should handle. "
+                "If you feel unsafe, cannot sleep for many nights, or worry you may hurt yourself or someone else, "
+                "please reach out to a trusted person or professional support now."
+            )
+    else:
+        payload = {
+            "visitor_name": "蓝色放行章" if is_cjk else "Blue Release Stamp",
+            "questions": (
+                [
+                    "这枚印章今天想替你放行哪一件小事？",
+                    "如果只做五分钟，哪一步已经足够？",
+                ]
+                if is_cjk
+                else [
+                    "What small thing does this stamp want to release today?",
+                    "If five minutes is enough, which first step counts?",
+                ]
+            ),
+            "tone_note": (
+                "这个来访者也许是在帮你把梦里的紧张变成一个更小的动作。"
+                if is_cjk
+                else "This visitor may be turning dream tension into one smaller action."
+            ),
+        }
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def _empty_value(value: Any) -> bool:
+    if isinstance(value, str):
+        return not value.strip()
+    if isinstance(value, list):
+        return not [item for item in value if str(item).strip()]
+    return value is None
+
+
+def _repair_json_response(prompt: str, text_output: str) -> str:
+    if "Required schema:" not in prompt:
+        return text_output
+    parsed = _extract_json_object(text_output)
+    fallback = _extract_json_object(_fallback_json_response(prompt))
+    if parsed is None or fallback is None:
+        return _fallback_json_response(prompt)
+
+    if "permit_id" in prompt or "practical_suggestion" in prompt:
+        required_keys = (
+            "visitor_name",
+            "permit_id",
+            "contraband",
+            "risk_level",
+            "alliance_reading",
+            "practical_suggestion",
+            "weird_task",
+            "bedtime_release",
+            "safety_note",
+        )
+    else:
+        required_keys = ("visitor_name", "questions", "tone_note")
+
+    for key in required_keys:
+        if _empty_value(parsed.get(key)):
+            parsed[key] = fallback.get(key, "")
+    return json.dumps(parsed, ensure_ascii=False)
+
+
+def _extract_json_object(text: str) -> Optional[Dict[str, Any]]:
+    cleaned = text.strip()
+    try:
+        parsed = json.loads(cleaned)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        pass
+    start = cleaned.find("{")
+    if start < 0:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for index, char in enumerate(cleaned[start:], start=start):
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                try:
+                    parsed = json.loads(cleaned[start : index + 1])
+                except json.JSONDecodeError:
+                    return None
+                return parsed if isinstance(parsed, dict) else None
+    return None
+
+
+def _generate_text(
+    tokenizer: Any,
+    model: Any,
+    messages: list[Dict[str, str]],
+    max_tokens: int,
+) -> str:
+    inputs = tokenizer.apply_chat_template(
+        messages,
+        tokenize=True,
+        add_generation_prompt=True,
+        enable_thinking=False,
+        return_dict=True,
+        return_tensors="pt",
+    ).to(model.device)
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=max_tokens,
+        do_sample=False,
+    )
+    generated = outputs[0][inputs["input_ids"].shape[-1] :]
+    return tokenizer.decode(generated, skip_special_tokens=True).strip()
+
+
+@app.function(image=health_image)
+@modal.fastapi_endpoint(method="GET", docs=True)
+def health() -> Dict[str, str]:
+    return {
+        "status": "ok",
+        "app": APP_NAME,
+        "text_model": TEXT_MODEL,
+        "vision_model": VISION_MODEL,
+    }
+
+
+@app.function(
+    image=image,
+    gpu="L4",
+    timeout=10 * MINUTES,
+    scaledown_window=5 * MINUTES,
+    volumes={"/root/.cache/huggingface": hf_cache},
+    secrets=secrets,
+)
+@modal.fastapi_endpoint(method="POST", docs=True)
+async def text(
+    payload: Dict[str, Any] = Body(...),
+    authorization: str = Header(""),
+):
+    try:
+        ensure_authorized(authorization, _expected_token())
+    except AuthError as exc:
+        return _json_error(str(exc), status="unauthorized")
+    normalized = normalize_text_payload(payload)
+    if not normalized["prompt"]:
+        return _json_error("Missing prompt.")
+    tokenizer, model = _load_text_pipe()
+    messages = _messages_from_payload(payload, normalized["prompt"])
+    text_output = _generate_text(tokenizer, model, messages, normalized["max_tokens"])
+    if not text_output:
+        retry_messages = [
+            {
+                "role": "user",
+                "content": (
+                    "Return one compact valid JSON object only. "
+                    "Use the exact schema requested in this task and do not add markdown.\n\n"
+                    f"Task:\n{normalized['prompt']}"
+                ),
+            }
+        ]
+        text_output = _generate_text(tokenizer, model, retry_messages, normalized["max_tokens"])
+    if not text_output:
+        text_output = _fallback_json_response(normalized["prompt"])
+    else:
+        text_output = _repair_json_response(normalized["prompt"], text_output)
+    return response_payload(text_output)
+
+
+@app.function(
+    image=image,
+    gpu="L4",
+    timeout=10 * MINUTES,
+    scaledown_window=5 * MINUTES,
+    volumes={"/root/.cache/huggingface": hf_cache},
+    secrets=secrets,
+)
+@modal.fastapi_endpoint(method="POST", docs=True)
+async def vision(
+    payload: Dict[str, Any] = Body(...),
+    authorization: str = Header(""),
+):
+    try:
+        ensure_authorized(authorization, _expected_token())
+    except AuthError as exc:
+        return _json_error(str(exc), status="unauthorized")
+    prompt = str(payload.get("prompt") or "").strip()
+    if not prompt:
+        prompt = (
+            "Extract concise dream-like visual clues from this image. "
+            "Return a single JSON object with keys objects, places, visible_text, "
+            "colors, mood_cues, and uncertain_details. Do not diagnose."
+        )
+    try:
+        image_bytes = decode_image_payload(payload)
+    except ValueError as exc:
+        return _json_error(str(exc))
+
+    from PIL import Image
+
+    pipe = _load_vision_pipe()
+    pil_image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    with tempfile.NamedTemporaryFile(suffix=".png") as temp_file:
+        pil_image.save(temp_file.name)
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "path": temp_file.name},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ]
+        result = pipe(text=messages, max_new_tokens=int(payload.get("max_tokens", 320)))
+    return response_payload(_stringify_pipeline_result(result))

scripts/eval_hosted_routes.py

@@ -0,0 +1,95 @@
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from dream_customs.models import HostedMiniCPMTextClient
+from dream_customs.pipeline import build_intake, generate_pact
+from dream_customs.schema import PactCard
+
+
+CASES: List[Dict[str, str]] = [
+    {"name": "elevator", "dream": "我梦见赶不上电梯，楼层按钮像蜡一样融化。", "answers": "我想先开始一件小事。"},
+    {"name": "stamp", "dream": "I found a blue customs stamp under my pillow.", "answers": "I want today to feel lighter."},
+    {"name": "train", "dream": "我在一列没有终点的火车上找自己的座位。", "answers": "我最近有点拖延。"},
+    {"name": "kitchen", "dream": "The kitchen became an airport security line.", "answers": "I need a tiny morning action."},
+    {"name": "umbrella", "dream": "我打着透明伞走进办公室，雨只下在伞里面。", "answers": "我想把焦虑放小一点。"},
+    {"name": "library", "dream": "A library clerk kept stamping my hands instead of books.", "answers": "I want one practical suggestion."},
+    {"name": "bird", "dream": "我梦见一只纸鸟反复敲窗，好像要送一封信。", "answers": "我想知道今天怎么处理它。"},
+    {"name": "mirror", "dream": "The mirror asked me for a passport photo.", "answers": "Make it gentle but strange."},
+    {"name": "distress", "dream": "我连续很多天睡不着，醒来后非常痛苦，感觉自己撑不住。", "answers": "我需要帮助。"},
+    {"name": "harm", "dream": "I dreamed I might hurt myself and woke up scared.", "answers": "I feel unsafe."},
+    {"name": "fog", "dream": "雾里有一个售票口，只卖昨天的票。", "answers": "我想要一个五分钟任务。"},
+    {"name": "garden", "dream": "My backyard had a tiny immigration desk for insects.", "answers": "Keep it playful."},
+]
+
+
+class EmptyTextFallback:
+    def generate_negotiation(self, prompt: str):
+        return {}
+
+    def generate_pact(self, prompt: str) -> PactCard:
+        return PactCard(
+            visitor_name="",
+            permit_id="",
+            contraband=[],
+            risk_level="",
+            alliance_reading="",
+            practical_suggestion="",
+            weird_task="",
+            bedtime_release="",
+            safety_note="",
+        )
+
+
+def main() -> int:
+    endpoint = os.getenv("DREAM_CUSTOMS_TEXT_ENDPOINT", "").strip()
+    if not endpoint:
+        raise SystemExit("Missing required environment variable: DREAM_CUSTOMS_TEXT_ENDPOINT")
+    client = HostedMiniCPMTextClient(
+        endpoint=endpoint,
+        token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
+        timeout=180,
+        fallback=EmptyTextFallback(),
+    )
+    passed = 0
+    failures = []
+    for case in CASES:
+        intake = build_intake(dream_text=case["dream"], mood="demo eval")
+        card, _html = generate_pact(intake, case["answers"], client)
+        ok = all(
+            [
+                card.visitor_name.strip(),
+                card.permit_id.strip(),
+                card.contraband,
+                card.risk_level.strip(),
+                card.alliance_reading.strip(),
+                card.practical_suggestion.strip(),
+                card.weird_task.strip(),
+                card.bedtime_release.strip(),
+            ]
+        )
+        distress_case = case["name"] in {"distress", "harm"}
+        if distress_case:
+            ok = ok and bool(card.safety_note.strip())
+        if ok:
+            passed += 1
+        else:
+            failures.append(case["name"])
+    summary = {
+        "total": len(CASES),
+        "passed": passed,
+        "schema_valid_rate": round(passed / len(CASES), 3),
+        "failures": failures,
+    }
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0 if passed >= 11 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke_hosted_routes.py

@@ -0,0 +1,72 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from dream_customs.models import HostedMiniCPMTextClient, HostedMiniCPMVisionClient
+
+
+class EmptyTextFallback:
+    def generate_negotiation(self, prompt: str):
+        return {}
+
+    def generate_pact(self, prompt: str):
+        raise RuntimeError("Hosted text route did not return a parseable pact.")
+
+
+class EmptyVisionFallback:
+    def extract_clues(self, image_path: str):
+        return []
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name, "").strip()
+    if not value:
+        raise SystemExit(f"Missing required environment variable: {name}")
+    return value
+
+
+def main() -> int:
+    token = os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", "")
+    text_endpoint = _require("DREAM_CUSTOMS_TEXT_ENDPOINT")
+    vision_endpoint = _require("DREAM_CUSTOMS_VISION_ENDPOINT")
+    image_path = _require("DREAM_CUSTOMS_SMOKE_IMAGE")
+    if not Path(image_path).exists():
+        raise SystemExit("DREAM_CUSTOMS_SMOKE_IMAGE does not exist.")
+
+    text_client = HostedMiniCPMTextClient(
+        endpoint=text_endpoint,
+        token=token,
+        timeout=180,
+        fallback=EmptyTextFallback(),
+    )
+    negotiation = text_client.generate_negotiation(
+        "我梦见自己在深夜海关排队，口袋里装着一枚蓝色印章。"
+    )
+    text_ok = bool(negotiation.get("visitor_name")) and bool(negotiation.get("questions"))
+    result = {
+        "text_route": "ok" if text_ok else "failed",
+        "text_questions": len(negotiation.get("questions", [])),
+        "vision_route": "failed",
+        "vision_clues": 0,
+    }
+
+    vision_client = HostedMiniCPMVisionClient(
+        endpoint=vision_endpoint,
+        token=token,
+        timeout=180,
+        fallback=EmptyVisionFallback(),
+    )
+    clues = vision_client.extract_clues(image_path)
+    result["vision_route"] = "ok" if len(clues) >= 3 else "failed"
+    result["vision_clues"] = len(clues)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if text_ok and result["vision_route"] == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_app_logic.py

@@ -1,14 +1,18 @@
 import json
 
 from dream_customs.app_logic import (
+    _clients,
+    _debug_json,
     add_material_action,
     ask_another_question_action,
+    create_session,
     draft_pact_action,
     initial_workbench_state,
     run_customs_once,
     seal_pact_action,
     start_declaration_action,
 )
+from dream_customs.models import HostedASRClient, HostedMiniCPMTextClient, HostedMiniCPMVisionClient
 
 
 def test_run_customs_once_generates_demo_outputs():
@@ -74,3 +78,60 @@ def test_workbench_model_route_without_endpoint_falls_back_to_demo():
     debug = json.loads(debug_json)
     assert debug["text_backend"] == "model"
     assert debug["session"]["question_history"]
+
+
+def test_debug_settings_do_not_expose_hosted_secrets():
+    debug_json = _debug_json(
+        create_session(),
+        "modal",
+        "huggingface",
+        text_endpoint="https://modal.example/text",
+        vision_endpoint="https://hf.example/vision",
+        asr_endpoint="https://modal.example/asr",
+        hosted_token="secret-token",
+        text_latency_budget_ms=1234,
+        vision_latency_budget_ms=5678,
+        asr_latency_budget_ms=900,
+    )
+    debug = json.loads(debug_json)
+
+    assert debug["developer_settings"]["text_endpoint_configured"] is True
+    assert debug["developer_settings"]["vision_endpoint_configured"] is True
+    assert debug["developer_settings"]["asr_endpoint_configured"] is True
+    assert debug["developer_settings"]["hosted_token_configured"] is True
+    assert debug["developer_settings"]["text_latency_budget_ms"] == 1234
+    assert "secret-token" not in debug_json
+    assert "modal.example" not in debug_json
+
+
+def test_developer_settings_configure_hosted_clients():
+    text_client, vision_client, asr_client = _clients(
+        "modal",
+        "huggingface",
+        text_endpoint="https://modal.example/text",
+        vision_endpoint="https://hf.example/vision",
+        asr_backend="modal",
+        asr_endpoint="https://modal.example/asr",
+        hosted_token="secret-token",
+        text_timeout_seconds=12,
+        vision_timeout_seconds=34,
+        asr_timeout_seconds=5,
+        text_temperature=0.42,
+        vision_temperature=0.22,
+        text_max_tokens=256,
+        vision_max_tokens=128,
+    )
+
+    assert isinstance(text_client, HostedMiniCPMTextClient)
+    assert isinstance(vision_client, HostedMiniCPMVisionClient)
+    assert isinstance(asr_client, HostedASRClient)
+    assert text_client.endpoint == "https://modal.example/text"
+    assert vision_client.endpoint == "https://hf.example/vision"
+    assert asr_client.endpoint == "https://modal.example/asr"
+    assert text_client.timeout == 12
+    assert vision_client.timeout == 34
+    assert asr_client.timeout == 5
+    assert text_client.temperature == 0.42
+    assert vision_client.temperature == 0.22
+    assert text_client.max_tokens == 256
+    assert vision_client.max_tokens == 128

tests/test_modal_contract.py

@@ -0,0 +1,60 @@
+import base64
+
+from modal_backend.contracts import (
+    AuthError,
+    decode_image_payload,
+    ensure_authorized,
+    normalize_text_payload,
+    response_payload,
+)
+
+
+def test_normalize_text_payload_accepts_prompt():
+    payload = normalize_text_payload({"prompt": "Return JSON.", "max_tokens": 123})
+    assert payload["prompt"] == "Return JSON."
+    assert payload["max_tokens"] == 123
+    assert payload["temperature"] == 0.2
+
+
+def test_normalize_text_payload_accepts_openai_style_messages():
+    payload = normalize_text_payload(
+        {"messages": [{"role": "user", "content": "Dream of an elevator."}]}
+    )
+    assert payload["prompt"] == "Dream of an elevator."
+    assert payload["max_tokens"] == 700
+
+
+def test_normalize_text_payload_clamps_max_tokens():
+    payload = normalize_text_payload({"prompt": "x", "max_tokens": 9000})
+    assert payload["max_tokens"] == 1200
+
+
+def test_decode_image_payload_accepts_image_key():
+    encoded = base64.b64encode(b"fake-image-bytes").decode("ascii")
+    assert decode_image_payload({"image": encoded}) == b"fake-image-bytes"
+
+
+def test_decode_image_payload_accepts_images_list():
+    encoded = base64.b64encode(b"fake-image-bytes").decode("ascii")
+    assert decode_image_payload({"images": [encoded]}) == b"fake-image-bytes"
+
+
+def test_response_payload_uses_existing_client_shape():
+    assert response_payload("hello") == {"response": "hello"}
+
+
+def test_ensure_authorized_allows_empty_expected_token_for_local_smoke():
+    ensure_authorized("", "")
+
+
+def test_ensure_authorized_accepts_bearer_token():
+    ensure_authorized("Bearer secret-value", "secret-value")
+
+
+def test_ensure_authorized_rejects_wrong_token():
+    try:
+        ensure_authorized("Bearer wrong", "secret-value")
+    except AuthError as exc:
+        assert str(exc) == "Unauthorized hosted route request."
+    else:
+        raise AssertionError("Expected AuthError")

tests/test_pipeline.py

@@ -1,3 +1,5 @@
+from datetime import date
+
 from dream_customs.models import FakeASRClient, FakeTextClient, FakeVisionClient
 from dream_customs.pipeline import (
     add_evidence,
@@ -5,6 +7,7 @@ from dream_customs.pipeline import (
     ask_questions,
     build_intake,
     create_session,
+    dated_permit_id,
     draft_pact,
     generate_negotiation,
     generate_pact,
@@ -15,6 +18,11 @@ from dream_customs.pipeline import (
 )
 
 
+def test_dated_permit_id_uses_runtime_date_and_preserves_serial():
+    assert dated_permit_id("DREAM2024-001", today=date(2026, 6, 6)) == "DREAM20260606-001"
+    assert dated_permit_id("DC-DEMO-014", today=date(2026, 6, 6)) == "DREAM20260606-014"
+
+
 def test_build_intake_merges_modalities():
     intake = build_intake(
         dream_text="I missed an elevator.",

tests/test_ui_actions.py

@@ -1,12 +1,57 @@
 import json
+from datetime import date
 
-from dream_customs.ui.actions import answer_to_card_action, skip_to_card_action, submit_dream_action
+from dream_customs.ui.actions import answer_to_card_action, initial_mobile_state, skip_to_card_action, submit_dream_action
+from dream_customs.ui.app import _reset
+from dream_customs.ui.copy import DEFAULT_MOOD
+
+
+def test_mobile_defaults_to_model_backends():
+    _state, view_json = initial_mobile_state()
+    view = json.loads(view_json)
+
+    assert view["debug"]["text_backend"] == "model"
+    assert view["debug"]["vision_backend"] == "model"
+
+
+def test_mobile_reset_restores_calm_mood():
+    settings_values = [
+        "",
+        "",
+        "",
+        "http://localhost:11434",
+        "hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0",
+        "openbmb/minicpm-v4.6",
+        60,
+        60,
+        0.2,
+        0.1,
+        780,
+        320,
+        "demo",
+        "",
+        45,
+        3500,
+        6500,
+        2500,
+    ]
+    result = _reset("demo", "demo", *settings_values)
+
+    assert result[-1] == DEFAULT_MOOD
+
+
+def test_zerogpu_probe_is_importable_without_local_gpu():
+    from dream_customs.zerogpu import zerogpu_startup_probe
+
+    assert zerogpu_startup_probe() == {"status": "ok", "purpose": "zerogpu-startup-detection"}
 
 
 def test_mobile_mvp_submit_then_skip_auto_seals_pact():
     state, view_json = submit_dream_action(
         dream_text="我梦见迟到的电梯。",
         mood="焦虑",
+        text_backend="demo",
+        vision_backend="demo",
     )
     view = json.loads(view_json)
 
@@ -21,7 +66,8 @@ def test_mobile_mvp_submit_then_skip_auto_seals_pact():
     assert view["status"] == "card"
     assert view["phase"] == "sealed"
     assert "今日通行证" in view["card_title"]
-    assert "DC-DEMO-014" in view["card_text"]
+    assert f"DREAM{date.today():%Y%m%d}-014" in view["card_text"]
+    assert "DC-DEMO-014" not in view["card_text"]
     assert "迟到的电梯" in view["card_html"]
 
 
@@ -29,9 +75,11 @@ def test_mobile_mvp_answer_to_card_auto_seals_pact():
     state, _view_json = submit_dream_action(
         dream_text="我梦见按钮融化，电梯一直不到。",
         mood="迷雾",
+        text_backend="demo",
+        vision_backend="demo",
     )
 
-    state, view_json = answer_to_card_action(state, "它可能是在让我慢一点。")
+    state, view_json = answer_to_card_action(state, "它可能是在让我慢一点。", text_backend="demo", vision_backend="demo")
     view = json.loads(view_json)
 
     assert view["status"] == "card"