Deploy Dream Customs app

.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+.DS_Store
+.superpowers/
+tmp/
+outputs/
+*.wav
+*.mp3
+*.m4a

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md - Dream Customs / 梦境海关
+
+## 语言规则
+
+- 默认使用中文回复用户。
+- 面向评审/README/Space 展示的文字可以中英双语，但不要牺牲中文表达的清晰度。
+
+## 项目定位
+
+- 当前项目是 Build Small Hackathon 的 `Dream Customs / 梦境海关`。
+- 核心定位：帮用户和昨晚的梦结盟，把不安转成第二天的小建议，把怪梦转成一件有趣的小事。
+- 这不是心理诊断、医疗建议或治疗工具。
+
+## 竞赛约束
+
+- 目标交付：Gradio app on Hugging Face Space。
+- 模型总参数必须 <= 32B。
+- 优先叙事赛道：An Adventure in Thousand Token Wood。
+- 次级叙事：Backyard AI，因为项目来自真实睡眠/做梦困扰。
+- demo 必须能在短视频中快速展示：输入梦境，获得今日盟约卡。
+
+## 模型规则
+
+- 首选模型组合：
+  - `openbmb/MiniCPM-V-4.6`：图片、草图、便签、截图理解。
+  - `openbmb/MiniCPM5-1B`：文本推理、梦境外交官人格、结构化输出和建议生成。
+- 不要在 MiniCPM 路线未验证前扩展到任意其他小模型。
+- 语音输入需要 ASR 适配器；ASR 只做转写，不承担梦境理解。
+- 首版不要实现语音输出，避免扩大部署风险。
+
+## 产品边界
+
+- 必须支持文字输入。
+- 应支持图片输入，用 MiniCPM-V-4.6 提取视觉线索。
+- 应支持语音输入，通过小 ASR 适配器转成文本。
+- 所有输入统一进入 `DreamIntake`，不要做成三套割裂产品。
+- 输出必须包含：
+  - dream visitor / 梦境来访者
+  - permit id / 入境编号
+  - contraband / 携带情绪违禁品
+  - risk level / 风险等级
+  - alliance reading / 结盟解读
+  - practical suggestion / 今日认真建议
+  - weird task / 5 分钟怪趣任务
+  - bedtime release / 睡前放行仪式
+  - safety note / 必要时的安全提示
+
+## 安全规则
+
+- 不做心理疾病诊断。
+- 不声称梦境有唯一含义。
+- 不输出恐吓性、宿命论、神秘绝对化内容。
+- 普通输出使用“也许”“可以把它当作”“今天先试试”这类非确定措辞。
+- 如果用户表达自伤、伤人、长期严重失眠、无法正常生活或极强痛苦，必须显示寻求可信任的人或专业支持的提示。
+
+## 文档优先级
+
+实现前先阅读：
+
+1. `docs/spec.md`
+2. `docs/prd.md`
+3. `docs/handoff.md`
+4. `docs/superpowers/plans/2026-06-05-dream-customs-mvp.md`
+5. `docs/dream-customs-concept/index.html`
+
+## 开发流程
+
+- 修改或实验前先确认工作目录是 `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon`。
+- 当前目录可能位于父级 `vlarepo` git root 下；不要误推到 VLA remote。
+- 如果需要正式提交，先确认是否已初始化/切换到 Dream Customs 专用仓库。
+- 在仓库归属未确认前，可以本地写文件，但不要强行 `git add` / `git commit` / `git push` 到父级 VLA 仓库。
+- 如果建立新功能分支，使用 `feature/xxx` 命名。
+
+## 实现原则
+
+- 先用 fake clients 打通 schema、safety、render、pipeline 和 Gradio UI。
+- 核心测试通过后再接真实 MiniCPM 模型。
+- 所有模型输出都必须经过 schema 校验。
+- JSON 解析失败时必须有修复或降级路径。
+- Text-only path 必须永远可用，作为 demo fallback。
+- Gradio 页面应优先移动端可用，因为用户可能在手机上记录梦。
+
+## 验收命令
+
+基础验收：
+
+```bash
+python -m pytest -q
+python app.py
+```
+
+人工验收：
+
+- 输入一段文字梦境，能生成盟约卡。
+- 上传一张草图或便签，视觉线索进入 `DreamIntake`。
+- 上传/录制语音后，有转写或清晰降级提示。
+- 输出不包含诊断、恐吓或医疗化建议。
+- 页面在手机宽度下可读。

README.md

@@ -4,12 +4,71 @@ emoji: ⚡
 colorFrom: blue
 colorTo: pink
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+sdk_version: 4.44.1
+python_version: "3.10"
 app_file: app.py
 pinned: false
 license: mit
-short_description: A playful, non-diagnostic dream customs clerk that turns dre
+short_description: Turn dream declarations into a playful next-day pact.
+models:
+  - openbmb/MiniCPM5-1B
+  - openbmb/MiniCPM-V-4.6
+tags:
+  - gradio
+  - minicpm
+  - build-small-hackathon
+  - dream-journal
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Dream Customs / 梦境海关
+
+A Build Small Hackathon Gradio app that helps users form a playful alliance with last night's dream.
+
+## Concept
+
+Dream Customs accepts dream declarations by text, image, or voice. It turns the dream into a gentle "customs negotiation" and returns a Today's Pact card: one practical suggestion, one weird 5-minute task, and one bedtime release phrase.
+
+## Models
+
+- `openbmb/MiniCPM-V-4.6` for image/sketch/note understanding.
+- `openbmb/MiniCPM5-1B` for dream negotiation and pact generation.
+- A small ASR adapter may be used only for voice transcription.
+- The app defaults to a stable demo backend so the local Gradio flow always works.
+- Optional Ollama adapters are included for local MiniCPM testing.
+
+## Run
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+python app.py
+```
+
+Open `http://127.0.0.1:7860`.
+
+## Optional Ollama Models
+
+```bash
+ollama pull hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0
+ollama pull openbmb/minicpm-v4.6
+```
+
+Then switch the UI engine controls from `demo` to `ollama`.
+
+Local smoke notes from this Mac mini:
+
+- Memory/size is fine: 16 GB RAM handled the local model downloads.
+- `hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0` loads in Ollama, but current output was malformed for JSON prompts.
+- `openbmb/minicpm-v4.6` pulled successfully, but current Ollama runner returned `unable to load model`.
+- Because of that, the MVP keeps Ollama optional and falls back to deterministic demo behavior.
+
+## Test
+
+```bash
+python -m pytest -q
+```
+
+## Safety
+
+This is not a therapy or diagnosis product. It gives playful reflection, small actions, and escalation copy for severe distress.

app.py

@@ -0,0 +1,133 @@
+import gradio as gr
+from gradio_client import utils as gradio_client_utils
+
+from dream_customs.app_logic import run_customs_once
+
+
+_ORIGINAL_SCHEMA_TO_TYPE = gradio_client_utils._json_schema_to_python_type
+
+
+def _json_schema_to_python_type(schema, defs):
+    # Gradio 4.44 can pass JSON Schema booleans here on newer dependency sets.
+    if isinstance(schema, bool):
+        return "Any" if schema else "None"
+    return _ORIGINAL_SCHEMA_TO_TYPE(schema, defs)
+
+
+gradio_client_utils._json_schema_to_python_type = _json_schema_to_python_type
+
+
+CSS = """
+body { background: #f6f1e7; }
+.gradio-container {
+  color: #17272f;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.dc-shell {
+  max-width: 1180px;
+  margin: 0 auto;
+}
+.dc-title h1 {
+  font-size: clamp(30px, 5vw, 56px);
+  line-height: 1;
+  margin-bottom: 4px;
+}
+.dc-title p {
+  color: #49626b;
+  font-size: 16px;
+  margin-top: 0;
+}
+.dc-stamp button {
+  background: #17313b !important;
+  border: 0 !important;
+  color: #fff8ed !important;
+  font-weight: 800 !important;
+}
+textarea, input, select {
+  font-size: 16px !important;
+}
+@media (max-width: 760px) {
+  .dc-title h1 { font-size: 34px; }
+  .dc-title p { font-size: 14px; }
+}
+"""
+
+
+def build_demo() -> gr.Blocks:
+    with gr.Blocks(css=CSS, title="Dream Customs") as demo:
+        with gr.Column(elem_classes=["dc-shell"]):
+            gr.Markdown(
+                """
+                # Dream Customs / 梦境海关
+                夜间来访者入境申报处
+                """,
+                elem_classes=["dc-title"],
+            )
+            with gr.Row():
+                with gr.Column(scale=5):
+                    dream_text = gr.Textbox(
+                        label="Dream declaration",
+                        lines=8,
+                        value="我梦见一部迟到的电梯，按钮都融化了，我一直到不了 14 楼。",
+                    )
+                    with gr.Row():
+                        image_input = gr.Image(label="Image evidence", type="filepath")
+                        audio_input = gr.Audio(label="Voice evidence", type="filepath")
+                    mood = gr.Dropdown(
+                        label="Current weather",
+                        choices=["foggy", "anxious", "curious", "tired", "restless", "calm"],
+                        value="foggy",
+                    )
+                    answers = gr.Textbox(
+                        label="Answers to the clerk",
+                        lines=4,
+                        value="我想和它结盟，但今天只想完成一件很小的事。",
+                    )
+                    with gr.Row():
+                        text_backend = gr.Radio(
+                            label="Text engine",
+                            choices=["demo", "ollama"],
+                            value="demo",
+                        )
+                        vision_backend = gr.Radio(
+                            label="Vision engine",
+                            choices=["demo", "ollama"],
+                            value="demo",
+                        )
+                    submit = gr.Button("Stamp clearance", elem_classes=["dc-stamp"])
+
+                with gr.Column(scale=6):
+                    negotiation = gr.Textbox(label="Customs questions", lines=7)
+                    pact_text = gr.Textbox(label="Pact manifest", lines=12)
+                    pact_html = gr.HTML(label="Today's pact card")
+                    debug_json = gr.Code(label="Debug manifest", language="json")
+
+            submit.click(
+                run_customs_once,
+                inputs=[dream_text, image_input, audio_input, mood, answers, text_backend, vision_backend],
+                outputs=[negotiation, pact_text, pact_html, debug_json],
+            )
+
+            gr.Examples(
+                examples=[
+                    [
+                        "梦见一间便利店漂在海上，收银员让我用旧日历付款。",
+                        "curious",
+                        "我想知道它到底在保护什么。",
+                    ],
+                    [
+                        "I found a tiny border checkpoint inside my pillow. The officer stamped my hand with blue ink.",
+                        "restless",
+                        "I want a small action that makes tomorrow less loud.",
+                    ],
+                ],
+                inputs=[dream_text, mood, answers],
+            )
+    return demo
+
+
+demo = build_demo()
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="127.0.0.1", server_port=7860, show_api=False, show_error=True)

docs/dream-customs-concept/index.html

@@ -0,0 +1,480 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>梦境海关 / Dream Customs Concept</title>
+  <style>
+    :root {
+      --ink: #102c3a;
+      --ink-soft: #36545c;
+      --paper: #fff8ea;
+      --mist: #d8edf0;
+      --mint: #c9dfd2;
+      --coral: #e85d4f;
+      --amber: #f2a65a;
+      --line: rgba(16, 44, 58, 0.18);
+      --shadow: 0 24px 70px rgba(16, 44, 58, 0.18);
+    }
+
+    * { box-sizing: border-box; }
+
+    body {
+      margin: 0;
+      color: var(--ink);
+      background:
+        radial-gradient(circle at 9% 12%, rgba(232, 93, 79, 0.18), transparent 28%),
+        radial-gradient(circle at 88% 4%, rgba(216, 237, 240, 0.95), transparent 24%),
+        linear-gradient(135deg, #f6ead8 0%, #f8f1e4 46%, #d7ece5 100%);
+      font-family: "Iowan Old Style", "Songti SC", "Noto Serif CJK SC", Georgia, serif;
+      letter-spacing: 0;
+      line-height: 1.62;
+    }
+
+    .page {
+      width: min(1180px, calc(100% - 40px));
+      margin: 0 auto;
+      padding: 28px 0 60px;
+    }
+
+    .stampbar {
+      display: flex;
+      justify-content: space-between;
+      gap: 14px;
+      align-items: center;
+      color: var(--ink-soft);
+      font-size: 14px;
+      margin-bottom: 22px;
+    }
+
+    .stampbar span {
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      padding: 8px 12px;
+      background: rgba(255, 248, 234, 0.72);
+    }
+
+    .hero {
+      min-height: 74vh;
+      display: grid;
+      grid-template-columns: 1.02fr 0.98fr;
+      gap: 34px;
+      align-items: center;
+      padding: 34px 0 42px;
+    }
+
+    .kicker {
+      color: var(--coral);
+      font-weight: 800;
+      text-transform: uppercase;
+      font-family: "Avenir Next Condensed", "Gill Sans", sans-serif;
+      letter-spacing: 0;
+      margin-bottom: 16px;
+    }
+
+    h1, h2, h3 {
+      margin: 0;
+      line-height: 1.06;
+      letter-spacing: 0;
+    }
+
+    h1 {
+      max-width: 760px;
+      font-size: clamp(54px, 8vw, 118px);
+      font-weight: 900;
+    }
+
+    h2 {
+      font-size: clamp(31px, 4vw, 58px);
+      margin-bottom: 22px;
+    }
+
+    h3 {
+      font-size: 23px;
+      margin-bottom: 10px;
+    }
+
+    .lead {
+      max-width: 660px;
+      margin: 24px 0 26px;
+      font-size: 22px;
+      color: var(--ink-soft);
+    }
+
+    .pillrow {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      margin-top: 28px;
+    }
+
+    .pill {
+      padding: 9px 13px;
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      background: rgba(255, 248, 234, 0.72);
+      font-size: 14px;
+      font-weight: 800;
+      font-family: "Avenir Next", "Gill Sans", sans-serif;
+    }
+
+    .hero-visual {
+      position: relative;
+    }
+
+    .hero-visual img,
+    .image-card img {
+      display: block;
+      width: 100%;
+      height: auto;
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+    }
+
+    .section {
+      padding: 70px 0 24px;
+    }
+
+    .band {
+      border-top: 1px solid var(--line);
+      padding-top: 46px;
+    }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+      gap: 18px;
+    }
+
+    .two {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 24px;
+      align-items: start;
+    }
+
+    .card {
+      background: rgba(255, 248, 234, 0.78);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 24px;
+      box-shadow: 0 10px 36px rgba(16, 44, 58, 0.08);
+    }
+
+    .card strong,
+    .flow-step strong {
+      color: var(--coral);
+    }
+
+    .flow {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 14px;
+    }
+
+    .flow-step {
+      min-height: 210px;
+      background: var(--ink);
+      color: var(--paper);
+      border-radius: 8px;
+      padding: 22px;
+      position: relative;
+      overflow: hidden;
+    }
+
+    .flow-step::after {
+      content: attr(data-no);
+      position: absolute;
+      right: 14px;
+      bottom: -16px;
+      font-size: 104px;
+      line-height: 1;
+      color: rgba(255, 248, 234, 0.12);
+      font-weight: 900;
+      font-family: Georgia, serif;
+    }
+
+    .flow-step:nth-child(2) { background: #2e6870; }
+    .flow-step:nth-child(3) { background: #7c6b45; }
+    .flow-step:nth-child(4) { background: #b64c43; }
+
+    .spec {
+      background: rgba(16, 44, 58, 0.92);
+      color: var(--paper);
+      border-radius: 8px;
+      padding: 24px;
+      font-family: "SF Mono", Menlo, Consolas, monospace;
+      font-size: 14px;
+      overflow-x: auto;
+      line-height: 1.5;
+    }
+
+    .output-sample {
+      background: var(--paper);
+      border: 3px solid var(--ink);
+      border-radius: 8px;
+      padding: 26px;
+      box-shadow: 12px 12px 0 rgba(16, 44, 58, 0.14);
+    }
+
+    .sample-head {
+      display: flex;
+      justify-content: space-between;
+      gap: 12px;
+      border-bottom: 2px dashed var(--line);
+      padding-bottom: 12px;
+      margin-bottom: 18px;
+      font-weight: 900;
+    }
+
+    .seal {
+      display: inline-block;
+      border: 3px solid var(--coral);
+      color: var(--coral);
+      border-radius: 999px;
+      padding: 8px 14px;
+      transform: rotate(-4deg);
+      font-weight: 900;
+      margin-top: 12px;
+    }
+
+    .note {
+      color: var(--ink-soft);
+      font-size: 15px;
+      margin-top: 14px;
+    }
+
+    .image-card {
+      margin: 26px 0;
+    }
+
+    .footer {
+      border-top: 1px solid var(--line);
+      margin-top: 70px;
+      padding-top: 22px;
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      color: var(--ink-soft);
+      font-size: 14px;
+    }
+
+    .deerflow {
+      color: var(--ink-soft);
+      opacity: 0.72;
+      text-decoration: none;
+      border-bottom: 1px solid rgba(16, 44, 58, 0.24);
+    }
+
+    @media (max-width: 860px) {
+      .page { width: min(100% - 26px, 1180px); }
+      .hero,
+      .two,
+      .grid,
+      .flow {
+        grid-template-columns: 1fr;
+      }
+      .hero { min-height: auto; padding-top: 18px; }
+      .stampbar,
+      .footer {
+        flex-direction: column;
+        align-items: flex-start;
+      }
+      .lead { font-size: 19px; }
+    }
+  </style>
+</head>
+<body>
+  <main class="page">
+    <div class="stampbar">
+      <span>Build Small Hackathon concept note</span>
+      <span>MiniCPM-V-4.6 + MiniCPM5-1B</span>
+    </div>
+
+    <section class="hero">
+      <div>
+        <div class="kicker">Dream Customs / 梦境海关</div>
+        <h1>和昨晚的梦结盟</h1>
+        <p class="lead">
+          一个三模态小模型应用：你用语音、图片或文字申报梦境。梦境海关把不安转成第二天的小建议，
+          把怪梦转成一件 5 分钟能完成的有趣小事。
+        </p>
+        <div class="pillrow">
+          <span class="pill">语音输入</span>
+          <span class="pill">图片/草图输入</span>
+          <span class="pill">文字输入</span>
+          <span class="pill">今日盟约卡</span>
+          <span class="pill">非诊断式睡眠陪伴</span>
+        </div>
+      </div>
+      <div class="hero-visual">
+        <img src="assets/dream-passport.svg" alt="梦境入境许可证插图">
+      </div>
+    </section>
+
+    <section class="section band">
+      <h2>产品定位</h2>
+      <div class="two">
+        <div class="card">
+          <h3>它不是梦境诊断器</h3>
+          <p>
+            梦境海关不告诉用户“你有什么心理问题”，也不把梦解释成病症。它把梦当成一个来访者：
+            也许荒诞，也许吵闹，但可以谈判、安置、盖章放行。
+          </p>
+        </div>
+        <div class="card">
+          <h3>它是第二天的小同盟</h3>
+          <p>
+            输出重点不是解释过去，而是给明天一个轻量动作：一条认真建议、一个怪趣任务、
+            一句睡前放行仪式。用户睡不好时，也能获得一点温柔的秩序感。
+          </p>
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>三模态申报入口</h2>
+      <div class="image-card">
+        <img src="assets/multimodal-intake.svg" alt="语音、图片、文字输入汇入 Dream Intake JSON 的流程图">
+      </div>
+      <div class="grid">
+        <div class="card">
+          <h3>语音</h3>
+          <p>
+            睡醒后直接说梦，先由很小的 ASR 适配器转写成文本。它只负责转写，不参与梦境理解，
+            保证 MiniCPM 仍是体验核心。
+          </p>
+        </div>
+        <div class="card">
+          <h3>图片</h3>
+          <p>
+            上传梦境草图、床边便签、截图或随手拍。MiniCPM-V-4.6 读取视觉线索：
+            人、地点、物件、颜色、文字和情绪暗示。
+          </p>
+        </div>
+        <div class="card">
+          <h3>文字</h3>
+          <p>
+            最稳定的主入口。用户直接写梦境内容、醒来后的感觉、反复出现的符号，
+            MiniCPM5-1B 进入结盟谈判。
+          </p>
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>MVP 体验流</h2>
+      <div class="flow">
+        <div class="flow-step" data-no="1">
+          <h3>申报</h3>
+          <p>用户用语音、图片或文字提交梦境。系统合并成统一的 Dream Intake JSON。</p>
+        </div>
+        <div class="flow-step" data-no="2">
+          <h3>来访者画像</h3>
+          <p>MiniCPM5-1B 把梦境命名为一个来访者，例如“迟到的电梯”。</p>
+        </div>
+        <div class="flow-step" data-no="3">
+          <h3>结盟谈判</h3>
+          <p>海关官提出 2-3 个温柔古怪的问题，帮助用户把梦转成可行动线索。</p>
+        </div>
+        <div class="flow-step" data-no="4">
+          <h3>今日盟约</h3>
+          <p>生成一张可截图分享的盟约卡：认真建议、怪趣任务、睡前放行。</p>
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>模型分工</h2>
+      <div class="two">
+        <div class="card">
+          <h3>MiniCPM-V-4.6：梦境目击证人</h3>
+          <p>
+            负责多模态感知：草图、便签、截图、照片中的视觉元素抽取。输出结构化线索，
+            不承担最终建议，避免视觉模型被迫做长文本人格化写作。
+          </p>
+        </div>
+        <div class="card">
+          <h3>MiniCPM5-1B：梦境外交官</h3>
+          <p>
+            负责核心体验：梦境来访者命名、谈判问题、今日建议、怪趣任务、睡前放行仪式。
+            1B 模型足够轻，和赛题“小而巧”的精神贴合。
+          </p>
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>Dream Intake JSON</h2>
+      <pre class="spec">{
+  "dream_text": "我梦见自己一直赶不上电梯，楼层按钮会融化。",
+  "visual_clues": ["歪斜电梯门", "蓝色楼道", "融化的数字 14"],
+  "mood": "焦虑但有点滑稽",
+  "recurring_symbols": ["电梯", "迟到", "融化的按钮"],
+  "uncertainty": "梦的后半段记不清",
+  "user_context": "最近晚上常做梦，睡醒后想获得第二天建议"
+}</pre>
+    </section>
+
+    <section class="section">
+      <h2>输出样例</h2>
+      <div class="two">
+        <div class="output-sample">
+          <div class="sample-head">
+            <span>梦境入境许可证</span>
+            <span>DC-06-05-014</span>
+          </div>
+          <p><strong>来访者：</strong>迟到的电梯</p>
+          <p><strong>携带物：</strong>未申报的焦虑、融化的按钮、一小袋没来得及开始的事。</p>
+          <p><strong>准入决定：</strong>准许入境，但必须在今天被安置成一个小动作。</p>
+          <p><strong>今日建议：</strong>提前 10 分钟开始一件最小的任务，不追求完成，只追求启动。</p>
+          <p><strong>怪趣任务：</strong>给电梯写一句道歉信：“抱歉总让你替我背迟到的锅。”</p>
+          <p><strong>睡前放行：</strong>“今日电梯已停靠，未完成事项明日再报关。”</p>
+          <span class="seal">SEALED</span>
+        </div>
+        <div class="image-card">
+          <img src="assets/alliance-card.svg" alt="今日盟约卡插图">
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>安全边界</h2>
+      <div class="grid">
+        <div class="card">
+          <h3>不诊断</h3>
+          <p>不输出心理疾病判断，不解释成创伤证据，不制造恐惧。</p>
+        </div>
+        <div class="card">
+          <h3>轻建议</h3>
+          <p>只给生活层面的温和建议和微行动，避免医疗化、绝对化和命令式措辞。</p>
+        </div>
+        <div class="card">
+          <h3>升级提示</h3>
+          <p>如果用户表达长期严重失眠、自伤念头或强烈痛苦，提示寻求专业帮助。</p>
+        </div>
+      </div>
+    </section>
+
+    <section class="section">
+      <h2>Demo 叙事</h2>
+      <div class="card">
+        <p>
+          视频可以从真实场景开始：晚上睡不好，早上醒来还记得一个怪梦。用户对着麦克风说几句，
+          又拍一张床边便签。系统把它转成梦境申报表，盖章签发今日盟约卡。
+          结尾展示那个 5 分钟怪趣任务真的被执行了。
+        </p>
+      </div>
+      <p class="note">
+        比赛定位：更偏 Thousand Token Wood，因为它是一个 AI 承重的怪异互动体验；
+        同时也能讲 Backyard AI，因为它来自真实睡眠困扰。
+      </p>
+    </section>
+
+    <footer class="footer">
+      <span>Dream Customs concept draft · Build Small Hackathon</span>
+      <a class="deerflow" href="https://deerflow.tech" target="_blank" rel="noreferrer">Created By Deerflow</a>
+    </footer>
+  </main>
+</body>
+</html>

docs/handoff.md

@@ -0,0 +1,131 @@
+# Dream Customs / 梦境海关 Handoff
+
+Last updated: 2026-06-05
+
+## Current State
+
+The project is in concept/spec stage. A visual HTML concept note already exists at:
+
+- `docs/dream-customs-concept/index.html`
+
+Supporting images:
+
+- `docs/dream-customs-concept/assets/dream-passport.svg`
+- `docs/dream-customs-concept/assets/multimodal-intake.svg`
+- `docs/dream-customs-concept/assets/alliance-card.svg`
+
+This handoff adds project context documents for implementation:
+
+- `docs/spec.md`
+- `docs/prd.md`
+- `docs/handoff.md`
+- `docs/superpowers/plans/2026-06-05-dream-customs-mvp.md`
+- `AGENTS.md`
+
+## Product Decision
+
+Build Dream Customs as a "dream alliance" app, not a dream diagnosis app.
+
+Final positioning:
+
+> 梦境海关帮你和昨晚的梦结盟：把不安转成明天的小建议，把怪梦转成一件有趣的小事。
+
+## Model Decision
+
+Use:
+
+- `openbmb/MiniCPM-V-4.6` for image/sketch/note understanding.
+- `openbmb/MiniCPM5-1B` for text reasoning, negotiation, and final output.
+
+Do not broaden to arbitrary small models unless MiniCPM paths fail.
+
+Voice input is allowed, but current MiniCPM pair does not directly transcribe raw audio. Use a small ASR adapter only for transcription. Keep dream understanding and final generation inside MiniCPM.
+
+## Contest Constraints
+
+- Build Small Hackathon.
+- Build window: 2026-06-05 to 2026-06-15.
+- App should ship as Gradio on Hugging Face Space.
+- Total model parameters must be <= 32B.
+- Strongest track: An Adventure in Thousand Token Wood.
+- Secondary narrative: Backyard AI due to real sleep/dream use case.
+
+## MVP User Flow
+
+1. User submits dream using text, image, voice, or a combination.
+2. Audio is transcribed by a small adapter.
+3. Image is converted into visual clues by MiniCPM-V-4.6.
+4. App builds a `DreamIntake` object.
+5. MiniCPM5-1B generates dream visitor and 2-3 negotiation questions.
+6. User answers or skips.
+7. MiniCPM5-1B generates final "Today's Pact" card.
+8. Gradio renders a screenshot-friendly HTML card.
+
+## Required Output Fields
+
+- `visitor_name`
+- `permit_id`
+- `contraband`
+- `risk_level`
+- `alliance_reading`
+- `practical_suggestion`
+- `weird_task`
+- `bedtime_release`
+- `safety_note`
+
+## Safety Boundary
+
+The product must never present itself as therapy, medical advice, or diagnosis. It should use playful, non-certain language. Severe distress should trigger a professional-help suggestion.
+
+## Recommended First Implementation
+
+Create a minimal Python package:
+
+```text
+app.py
+requirements.txt
+README.md
+dream_customs/
+  __init__.py
+  schema.py
+  prompts.py
+  safety.py
+  render.py
+  pipeline.py
+  models.py
+tests/
+  test_schema.py
+  test_safety.py
+  test_render.py
+  test_pipeline.py
+```
+
+Start with mocked model clients and deterministic examples. Add real model loading only after schema, safety, rendering, and pipeline tests pass.
+
+## Implementation Priorities
+
+1. Text-only flow.
+2. Card rendering.
+3. Safety layer.
+4. Image clue extraction.
+5. Voice transcription adapter.
+6. Demo examples.
+7. Space packaging.
+
+## Known Repository Issue
+
+The current directory is under git root `/Users/junhaocheng`, whose remote is `adjcjh777/vlarepo.git`. This is likely not the intended Build Small repository. Also, `.git/info/exclude` currently ignores paths beneath this workspace root.
+
+Do not push these files to the VLA remote by accident. Before implementation, either:
+
+1. initialize a dedicated repo in `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon`, or
+2. move this context into the intended Build Small repository/Space repo.
+
+## Open Questions For User
+
+These do not block initial scaffolding:
+
+- Should the demo language be Chinese-only or bilingual?
+- Which Hugging Face Space name should be used?
+- Should we reuse any previous `build-small-relics` assets, or keep Dream Customs separate?
+- Which ASR adapter is acceptable for the hackathon submission?

docs/prd.md

@@ -0,0 +1,229 @@
+# Dream Customs / 梦境海关 PRD
+
+Last updated: 2026-06-05
+
+## 1. Executive Summary
+
+### Problem Statement
+
+Users who wake up from frequent or vivid dreams may feel unsettled, tired, or mentally cluttered. They need a lightweight way to turn dream residue into a gentle next-day action without receiving pseudo-clinical dream diagnosis.
+
+### Proposed Solution
+
+Dream Customs is a Gradio app that accepts voice, image, and text dream declarations, normalizes them into a structured dream intake, and uses MiniCPM models to generate a playful "dream alliance" card with practical advice, a weird 5-minute task, and a bedtime release phrase.
+
+### Success Criteria
+
+- A user can complete the core flow from input to final card in <= 90 seconds on the hosted demo.
+- At least 90% of demo runs produce a parseable final output object matching the required schema.
+- At least 5 real users can understand the output without extra explanation and rate it >= 4/5 for delight.
+- At least 3 real users report that the "today's pact" feels actionable.
+- The app runs with total model parameters <= 32B and is packaged for Gradio/Hugging Face Space.
+
+## 2. User Experience & Functionality
+
+### User Personas
+
+1. Primary persona: vivid dreamer.
+   - Recently sleeps poorly or wakes with strong dream fragments.
+   - Wants a small morning ritual, not therapy.
+
+2. Secondary persona: playful AI explorer.
+   - Wants a strange AI experience worth showing a friend.
+   - Cares about creativity and shareable outputs.
+
+3. Demo viewer / judge.
+   - Needs to understand the interaction in under one minute.
+   - Looks for clear small-model fit and Gradio polish.
+
+### User Stories
+
+#### Story 1: Text Dream Declaration
+
+As a vivid dreamer, I want to type my dream so that I can get a next-day pact even if I have no image or audio.
+
+Acceptance criteria:
+
+- User can submit text-only input.
+- App creates a valid `DreamIntake` object.
+- Final card includes dream visitor, practical suggestion, weird task, and bedtime release phrase.
+
+#### Story 2: Image Dream Declaration
+
+As a user who remembers images better than words, I want to upload a sketch or bedside note so that the system can use visual dream clues.
+
+Acceptance criteria:
+
+- User can upload one image.
+- MiniCPM-V-4.6 extracts at least 3 visual clues when visible content exists.
+- Visual clues are included in the final `DreamIntake`.
+- If image extraction fails, text-only flow still works.
+
+#### Story 3: Voice Dream Declaration
+
+As a half-awake user, I want to speak my dream so that I do not need to type immediately after waking.
+
+Acceptance criteria:
+
+- User can record or upload an audio clip.
+- ASR adapter returns a transcript.
+- Transcript is visible/editable before final submission or transparently included in the declaration.
+- If ASR fails, user receives a concise fallback message and can type manually.
+
+#### Story 4: Alliance Negotiation
+
+As a user, I want the AI to ask me a few questions so that the final advice feels connected to my dream.
+
+Acceptance criteria:
+
+- App generates 2-3 questions.
+- User can answer all, answer some, or skip.
+- Skip path still generates a final card.
+
+#### Story 5: Today's Pact Card
+
+As a user, I want a visually clear output card so that I can screenshot or share the result.
+
+Acceptance criteria:
+
+- Card includes all required output fields.
+- Card is readable on mobile and desktop.
+- Card avoids medical or diagnostic framing.
+- Card includes a short safety note only when needed.
+
+### Non-Goals
+
+- Medical diagnosis or therapy.
+- Sleep-stage tracking.
+- Long-term journaling database.
+- Account creation.
+- Voice output in MVP.
+- Social feed or leaderboard.
+- Fine-tuning during the hackathon MVP.
+
+## 3. AI System Requirements
+
+### Tool Requirements
+
+- MiniCPM-V-4.6 for image-to-text visual clue extraction.
+- MiniCPM5-1B for text reasoning, persona, structured output, and alliance card generation.
+- A small ASR adapter for voice-to-text. This adapter is not the core AI experience.
+- Gradio for UI.
+- Optional HTML/CSS card renderer.
+
+### Prompt Requirements
+
+Prompts must:
+
+- Ask for JSON-compatible output.
+- Keep the tone playful, gentle, and non-clinical.
+- Avoid strong claims about dream meaning.
+- Include a safety boundary for severe distress.
+- Keep final advice small enough to execute in 5-10 minutes.
+
+### Evaluation Strategy
+
+Create an eval set with at least 12 dream inputs:
+
+- 4 text-only dreams.
+- 3 image-assisted dreams.
+- 3 voice-transcript dreams.
+- 2 distress-edge cases.
+
+Measure:
+
+- Schema validity.
+- Tone safety.
+- Practicality of advice.
+- Weird-task delight.
+- Ability to recover from missing modality.
+
+Pass thresholds:
+
+- Schema validity: >= 90%.
+- No diagnostic language in ordinary cases: 100%.
+- Safety note appears in distress-edge cases: >= 90%.
+- Human delight rating on 5 demo cases: average >= 4/5.
+
+## 4. Technical Specifications
+
+### Architecture Overview
+
+```text
+Gradio inputs
+  -> text input
+  -> image upload -> MiniCPM-V-4.6 visual clue extractor
+  -> audio upload/record -> ASR adapter
+  -> DreamIntake builder
+  -> MiniCPM5-1B customs officer prompt
+  -> negotiation questions
+  -> final MiniCPM5-1B pact prompt
+  -> HTML card renderer
+```
+
+### Core Components
+
+- `app.py`: Gradio UI composition and event wiring.
+- `dream_customs/schema.py`: dataclasses or Pydantic models for inputs and outputs.
+- `dream_customs/models.py`: model/client loading and inference wrappers.
+- `dream_customs/prompts.py`: prompt templates.
+- `dream_customs/pipeline.py`: orchestration logic.
+- `dream_customs/safety.py`: lightweight safety checks and copy.
+- `dream_customs/render.py`: HTML card rendering.
+- `tests/`: schema, prompt, safety, and pipeline unit tests with mocked model outputs.
+
+### Integration Points
+
+- Hugging Face Space runtime.
+- Hugging Face model downloads or inference endpoints.
+- Gradio audio, image, and text components.
+- Optional model cache in Space environment.
+
+### Security & Privacy
+
+- Do not persist user dreams by default.
+- Do not log raw dream text or uploaded images in production demo logs.
+- Provide visible copy: "This is a playful reflection tool, not medical advice."
+- Do not require account login.
+
+## 5. Risks & Roadmap
+
+### Phased Rollout
+
+#### MVP
+
+- Text, image, and voice input.
+- Dream intake normalization.
+- MiniCPM-V-4.6 image clue extraction.
+- MiniCPM5-1B negotiation and final card.
+- HTML output card.
+- Safety boundary.
+
+#### v1.1
+
+- More polished card export.
+- Better example gallery.
+- Optional bilingual output.
+- More robust eval harness.
+
+#### v2.0
+
+- Voice output through VoxCPM2.
+- Local dream history stored only in browser/session.
+- Multiple customs officer styles.
+
+### Technical Risks
+
+- MiniCPM-V-4.6 may be heavy for Space hardware if loaded locally.
+- MiniCPM5-1B output may fail strict JSON without repair.
+- ASR adapter may complicate dependencies.
+- Audio input on mobile browsers may behave inconsistently.
+- Safety classification may be too weak if only prompt-based.
+
+### Mitigations
+
+- Keep text-only demo path always functional.
+- Add JSON repair and schema validation.
+- Use examples with fixed sample media for demo recording.
+- Make ASR optional and fallback to manual transcript.
+- Keep image extraction output concise to reduce latency.

docs/spec.md

@@ -0,0 +1,236 @@
+# Dream Customs / 梦境海关 Product Spec
+
+Last updated: 2026-06-05
+
+## 1. One-Line Concept
+
+梦境海关帮用户和昨晚的梦结盟：用户用语音、图片或文字申报梦境，系统把不安转成第二天的小建议，把怪梦转成一件 5 分钟能完成的有趣小事。
+
+## 2. Contest Fit
+
+- Event: Build Small Hackathon.
+- Build window: 2026-06-05 to 2026-06-15.
+- Deployment target: Gradio app on Hugging Face Space.
+- Model constraint: total model parameters must be <= 32B.
+- Primary track fit: An Adventure in Thousand Token Wood, because the AI is the load-bearing delight of the experience.
+- Secondary story: Backyard AI, because the concept comes from a real sleep problem: frequent vivid dreams and poor sleep.
+- Model family constraint: prioritize MiniCPM models before considering any unrelated small model.
+
+## 3. Core User Problem
+
+The user wakes up after vivid or unsettling dreams and wants a quick, non-clinical way to make sense of the dream before the day begins. Existing dream tools often feel either too mystical, too diagnostic, or too generic. This product should feel like a playful ritual that gives emotional order without pretending to be therapy.
+
+## 4. Product Principles
+
+1. Do not diagnose.
+2. Do not frighten the user.
+3. Convert dream residue into a small next-day action.
+4. Keep the output weird enough to show a friend.
+5. Make the AI the main experience, not a helper hidden behind a form.
+6. Keep the MVP stable enough for Gradio Space and demo-video recording.
+
+## 5. User Inputs
+
+All inputs are normalized into one `DreamIntake` object so the app does not become three separate products.
+
+### 5.1 Text Input
+
+The user writes:
+
+- Dream narrative.
+- Wake-up mood.
+- Repeated symbols.
+- Any second-day concern or wish.
+
+### 5.2 Image Input
+
+The user uploads:
+
+- A dream sketch.
+- A bedside note.
+- A screenshot or photo related to the dream.
+- A quick doodle drawn after waking.
+
+MiniCPM-V-4.6 extracts visual clues and returns structured text.
+
+### 5.3 Voice Input
+
+The user speaks the dream immediately after waking.
+
+Implementation note: MiniCPM-V-4.6 and MiniCPM5-1B are not raw audio ASR models. Voice input needs a small transcription adapter. The adapter only converts audio to text; dream understanding remains MiniCPM-driven.
+
+## 6. Dream Intake Schema
+
+```json
+{
+  "dream_text": "我梦见自己一直赶不上电梯，楼层按钮会融化。",
+  "voice_transcript": "我梦见我一直赶不上电梯...",
+  "visual_clues": ["歪斜电梯门", "蓝色楼道", "融化的数字 14"],
+  "mood": "焦虑但有点滑稽",
+  "recurring_symbols": ["电梯", "迟到", "融化的按钮"],
+  "uncertainty": "梦的后半段记不清",
+  "user_context": "最近晚上常做梦，睡醒后想获得第二天建议"
+}
+```
+
+## 7. Model Responsibilities
+
+### MiniCPM-V-4.6
+
+Role: dream witness.
+
+Responsibilities:
+
+- Read sketches, notes, screenshots, and photos.
+- Extract objects, locations, visible text, colors, spatial relationships, and emotional cues.
+- Return concise JSON-compatible visual clues.
+
+Non-responsibilities:
+
+- Do not generate the final alliance card.
+- Do not provide psychological interpretation.
+
+### MiniCPM5-1B
+
+Role: dream diplomat.
+
+Responsibilities:
+
+- Merge dream text, voice transcript, and visual clues.
+- Name the dream visitor.
+- Ask 2-3 alliance negotiation questions.
+- Generate the final alliance card.
+- Keep tone playful, gentle, and non-clinical.
+
+## 8. MVP User Flow
+
+1. User opens Gradio app.
+2. User submits any combination of text, image, and voice.
+3. App transcribes voice if present.
+4. App calls MiniCPM-V-4.6 if image is present.
+5. App builds `DreamIntake`.
+6. MiniCPM5-1B generates a dream visitor profile and 2-3 follow-up questions.
+7. User answers questions or clicks "skip / refuse cooperation".
+8. MiniCPM5-1B generates a final alliance card.
+9. App renders the card as a shareable visual block and plain text.
+
+## 9. Output Contract
+
+The final card must include:
+
+- Dream visitor name.
+- Entry permit number.
+- Carried emotional contraband.
+- Risk level, phrased playfully.
+- Alliance reading: what the dream may be trying to protect.
+- One practical next-day suggestion.
+- One 5-minute weird task.
+- One bedtime release phrase.
+- Safety note if the input indicates severe distress.
+
+Example:
+
+```json
+{
+  "visitor_name": "迟到的电梯",
+  "permit_id": "DC-0605-014",
+  "contraband": ["未申报的焦虑", "融化的按钮", "一小袋没来得及开始的事"],
+  "risk_level": "橙色：需要被安置，但不需要被害怕",
+  "alliance_reading": "这个梦像是在提醒你，今天不要把启动一件事和完成一件事混成同一个压力。",
+  "practical_suggestion": "提前 10 分钟开始一件最小的任务，只要求打开它。",
+  "weird_task": "给电梯写一句道歉信：抱歉总让你替我背迟到的锅。",
+  "bedtime_release": "今日电梯已停靠，未完成事项明日再报关。",
+  "safety_note": ""
+}
+```
+
+## 10. UX Structure
+
+### Screen 1: Dream Declaration Desk
+
+Inputs:
+
+- Textbox for dream notes.
+- Image upload for dream sketch or bedside note.
+- Audio input for spoken dream.
+- Optional mood selector.
+
+Primary action:
+
+- "Submit to Customs"
+
+### Screen 2: Alliance Negotiation
+
+Content:
+
+- Dream visitor name.
+- 2-3 questions from the customs officer.
+- Buttons: answer, skip, refuse cooperation.
+
+### Screen 3: Today's Pact Card
+
+Content:
+
+- Card-style result.
+- Copy text button.
+- Download/share image target if feasible.
+- "Release this dream for tonight" reset action.
+
+## 11. Safety Boundaries
+
+The app must:
+
+- Avoid diagnoses, medical claims, or certainty about dream meaning.
+- Avoid telling users that a dream proves trauma, illness, or danger.
+- Use language such as "may be", "could be treated as", and "for today, try".
+- If the user mentions self-harm, intent to harm others, severe insomnia, panic, or inability to function, show a supportive escalation note.
+
+Escalation copy:
+
+> This dream sounds heavier than a playful customs ritual should handle. If you feel unsafe, unable to sleep for many nights, or worried you may hurt yourself or someone else, please reach out to a trusted person or professional support now.
+
+## 12. Recommended MVP Scope
+
+Included:
+
+- Gradio app.
+- Text input.
+- Image input through MiniCPM-V-4.6.
+- Voice input through small ASR adapter.
+- MiniCPM5-1B prompt flow.
+- Result card in HTML.
+- Example mode for demo stability.
+- Basic safety classifier prompt or rule layer.
+
+Excluded from MVP:
+
+- Voice output.
+- Long-term account system.
+- Medical sleep tracking.
+- Dream history database.
+- Personalized therapy plans.
+- Multi-user social feed.
+
+## 13. Grill Questions And Recommended Answers
+
+1. Is this a therapy tool?
+   - Recommended answer: no. It is a playful reflection and next-day ritual tool.
+
+2. Which track should the submission emphasize?
+   - Recommended answer: Thousand Token Wood first, Backyard AI second.
+
+3. Should voice be core?
+   - Recommended answer: voice input yes, voice output no for MVP.
+
+4. Should the image input be mandatory?
+   - Recommended answer: no. Image is a strong MiniCPM-V demo path but text alone must work.
+
+5. What is the winning demo moment?
+   - Recommended answer: user speaks a dream, uploads a quick sketch, and receives a strange but useful "Today's Pact" card.
+
+## 14. Open Questions
+
+- Which ASR adapter should be used on Hugging Face Space for the MVP?
+- Should the first demo be in Chinese, English, or bilingual?
+- Do we want to submit under the same team/repo as the earlier Ordinary Relics MVP, or create a new Space?
+- Should the visual card support image download in MVP or only screenshot-friendly HTML?

docs/superpowers/plans/2026-06-05-dream-customs-mvp.md

@@ -0,0 +1,812 @@
+# Dream Customs MVP 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:** Build a Gradio MVP for Dream Customs that accepts text, image, and voice dream declarations and returns a playful, safe "Today's Pact" card powered primarily by MiniCPM5-1B plus MiniCPM-V-4.6.
+
+**Architecture:** The app normalizes all modalities into a `DreamIntake` schema, then runs a two-stage pipeline: dream visitor negotiation and final pact generation. The MVP starts with mocked model clients and deterministic tests, then swaps in MiniCPM inference wrappers after core behavior is stable.
+
+**Tech Stack:** Python, Gradio, pytest, Pydantic or dataclasses, Hugging Face Transformers or compatible inference endpoints, MiniCPM-V-4.6, MiniCPM5-1B, small ASR adapter.
+
+---
+
+## Execution Status 2026-06-05
+
+- [x] Project scaffold, README, package marker, pytest path hook.
+- [x] `DreamIntake` and `PactCard` schemas.
+- [x] Safety layer with escalation copy for severe distress.
+- [x] Prompt templates for visual clue extraction, negotiation, and pact generation.
+- [x] HTML pact card renderer.
+- [x] Fake model clients and deterministic pipeline.
+- [x] Ollama adapters for MiniCPM5 text and MiniCPM-V vision, kept optional.
+- [x] Gradio app with text, image, voice inputs and backend selectors.
+- [x] Local smoke checks: pytest, app import, `get_api_info`, HTTP 200, `/config`, `/api/predict`.
+- [x] Local Ollama pull: `hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0` and `openbmb/minicpm-v4.6`.
+- [ ] Submission packaging, demo video script, and final material checklist.
+
+Implementation note: detailed steps below are the original TDD plan. The final code keeps the demo backend as default because local Ollama smoke tests showed MiniCPM5 GGUF returning malformed output and MiniCPM-V failing to load in the current Ollama runner.
+
+---
+
+## File Structure
+
+- Create `app.py`: Gradio UI and event handlers.
+- Create `requirements.txt`: Space dependencies.
+- Create `README.md`: project overview, model constraints, running instructions.
+- Create `dream_customs/__init__.py`: package marker.
+- Create `dream_customs/schema.py`: input and output data models.
+- Create `dream_customs/prompts.py`: prompt templates and formatting helpers.
+- Create `dream_customs/safety.py`: safety checks and escalation copy.
+- Create `dream_customs/render.py`: HTML card rendering.
+- Create `dream_customs/models.py`: model wrapper interfaces, fake clients, and later real model adapters.
+- Create `dream_customs/pipeline.py`: orchestration from inputs to final card.
+- Create `tests/test_schema.py`: schema tests.
+- Create `tests/test_safety.py`: safety tests.
+- Create `tests/test_render.py`: render tests.
+- Create `tests/test_pipeline.py`: pipeline tests with fake clients.
+
+## Task 1: Project Scaffold
+
+**Files:**
+- Create: `requirements.txt`
+- Create: `README.md`
+- Create: `dream_customs/__init__.py`
+- Create: `tests/conftest.py`
+
+- [ ] **Step 1: Create dependency file**
+
+Write `requirements.txt`:
+
+```text
+gradio>=5.0
+pydantic>=2.7
+pytest>=8.0
+transformers>=4.56
+torch
+pillow
+soundfile
+```
+
+- [ ] **Step 2: Create README**
+
+Write `README.md`:
+
+````markdown
+# Dream Customs / 梦境海关
+
+A Build Small Hackathon Gradio app that helps users form a playful alliance with last night's dream.
+
+## Models
+
+- MiniCPM-V-4.6 for image/sketch understanding.
+- MiniCPM5-1B for dream negotiation and pact generation.
+- A small ASR adapter may be used only for voice transcription.
+
+## Run
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+## Safety
+
+This is not a therapy or diagnosis product. It gives playful reflection, small actions, and escalation copy for severe distress.
+````
+
+- [ ] **Step 3: Create package marker**
+
+Write `dream_customs/__init__.py`:
+
+```python
+"""Dream Customs package."""
+```
+
+- [ ] **Step 4: Create pytest config hook**
+
+Write `tests/conftest.py`:
+
+```python
+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))
+```
+
+- [ ] **Step 5: Run scaffold check**
+
+Run:
+
+```bash
+python -m pytest -q
+```
+
+Expected:
+
+```text
+no tests ran
+```
+
+- [ ] **Step 6: Commit scaffold**
+
+```bash
+git add requirements.txt README.md dream_customs/__init__.py tests/conftest.py
+git commit -m "feat: scaffold dream customs app"
+```
+
+## Task 2: Data Schemas
+
+**Files:**
+- Create: `dream_customs/schema.py`
+- Create: `tests/test_schema.py`
+
+- [ ] **Step 1: Write failing schema tests**
+
+Write `tests/test_schema.py`:
+
+```python
+from dream_customs.schema import DreamIntake, PactCard
+
+
+def test_dream_intake_defaults_lists():
+    intake = DreamIntake(dream_text="I missed an elevator.")
+    assert intake.dream_text == "I missed an elevator."
+    assert intake.visual_clues == []
+    assert intake.recurring_symbols == []
+
+
+def test_pact_card_requires_core_fields():
+    card = PactCard(
+        visitor_name="Late Elevator",
+        permit_id="DC-0001",
+        contraband=["unfiled anxiety"],
+        risk_level="orange",
+        alliance_reading="The dream asks for a smaller start.",
+        practical_suggestion="Open one task ten minutes early.",
+        weird_task="Write the elevator an apology note.",
+        bedtime_release="Today the elevator has docked.",
+    )
+    assert card.safety_note == ""
+    assert "Late Elevator" in card.to_plain_text()
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+python -m pytest tests/test_schema.py -q
+```
+
+Expected: FAIL with `ModuleNotFoundError` or missing model classes.
+
+- [ ] **Step 3: Implement schemas**
+
+Write `dream_customs/schema.py`:
+
+```python
+from pydantic import BaseModel, Field
+
+
+class DreamIntake(BaseModel):
+    dream_text: str = ""
+    voice_transcript: str = ""
+    visual_clues: list[str] = Field(default_factory=list)
+    mood: str = ""
+    recurring_symbols: list[str] = Field(default_factory=list)
+    uncertainty: str = ""
+    user_context: str = ""
+
+    def merged_text(self) -> str:
+        parts = [
+            self.dream_text.strip(),
+            self.voice_transcript.strip(),
+            "Visual clues: " + ", ".join(self.visual_clues) if self.visual_clues else "",
+            "Mood: " + self.mood.strip() if self.mood else "",
+            "Recurring symbols: " + ", ".join(self.recurring_symbols) if self.recurring_symbols else "",
+            "Uncertainty: " + self.uncertainty.strip() if self.uncertainty else "",
+            "Context: " + self.user_context.strip() if self.user_context else "",
+        ]
+        return "\n".join(part for part in parts if part)
+
+
+class PactCard(BaseModel):
+    visitor_name: str
+    permit_id: str
+    contraband: list[str]
+    risk_level: str
+    alliance_reading: str
+    practical_suggestion: str
+    weird_task: str
+    bedtime_release: str
+    safety_note: str = ""
+
+    def to_plain_text(self) -> str:
+        contraband = ", ".join(self.contraband)
+        lines = [
+            f"Dream visitor: {self.visitor_name}",
+            f"Permit: {self.permit_id}",
+            f"Contraband: {contraband}",
+            f"Risk level: {self.risk_level}",
+            f"Alliance reading: {self.alliance_reading}",
+            f"Today's suggestion: {self.practical_suggestion}",
+            f"Weird task: {self.weird_task}",
+            f"Bedtime release: {self.bedtime_release}",
+        ]
+        if self.safety_note:
+            lines.append(f"Safety note: {self.safety_note}")
+        return "\n".join(lines)
+```
+
+- [ ] **Step 4: Run schema tests**
+
+Run:
+
+```bash
+python -m pytest tests/test_schema.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit schemas**
+
+```bash
+git add dream_customs/schema.py tests/test_schema.py
+git commit -m "feat: add dream customs schemas"
+```
+
+## Task 3: Safety Layer
+
+**Files:**
+- Create: `dream_customs/safety.py`
+- Create: `tests/test_safety.py`
+
+- [ ] **Step 1: Write failing safety tests**
+
+Write `tests/test_safety.py`:
+
+```python
+from dream_customs.safety import needs_escalation, safety_note
+
+
+def test_ordinary_dream_does_not_escalate():
+    assert not needs_escalation("I dreamed about a strange elevator.")
+
+
+def test_self_harm_text_escalates():
+    assert needs_escalation("I might hurt myself if I cannot sleep.")
+
+
+def test_safety_note_mentions_professional_support():
+    assert "professional support" in safety_note().lower()
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+python -m pytest tests/test_safety.py -q
+```
+
+Expected: FAIL with missing module or functions.
+
+- [ ] **Step 3: Implement safety functions**
+
+Write `dream_customs/safety.py`:
+
+```python
+ESCALATION_TERMS = (
+    "hurt myself",
+    "kill myself",
+    "suicide",
+    "self-harm",
+    "hurt someone",
+    "many nights",
+    "cannot function",
+    "panic attack",
+    "想伤害自己",
+    "自杀",
+    "伤害别人",
+    "很多天睡不着",
+    "无法正常生活",
+)
+
+
+def needs_escalation(text: str) -> bool:
+    lowered = text.lower()
+    return any(term in lowered for term in ESCALATION_TERMS)
+
+
+def safety_note() -> str:
+    return (
+        "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."
+    )
+```
+
+- [ ] **Step 4: Run safety tests**
+
+Run:
+
+```bash
+python -m pytest tests/test_safety.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit safety layer**
+
+```bash
+git add dream_customs/safety.py tests/test_safety.py
+git commit -m "feat: add dream customs safety layer"
+```
+
+## Task 4: Prompt Templates
+
+**Files:**
+- Create: `dream_customs/prompts.py`
+
+- [ ] **Step 1: Create prompt module**
+
+Write `dream_customs/prompts.py`:
+
+```python
+from dream_customs.schema import DreamIntake
+
+
+def visual_clue_prompt() -> str:
+    return (
+        "You are the witness clerk at Dream Customs. Extract concise visual clues "
+        "from this dream sketch, note, screenshot, or photo. Return JSON with keys: "
+        "objects, places, visible_text, colors, mood_cues, uncertain_details. "
+        "Do not diagnose the user."
+    )
+
+
+def negotiation_prompt(intake: DreamIntake) -> str:
+    return f"""
+You are the Dream Customs diplomat. The user is not asking for diagnosis.
+Treat the dream as a strange visitor that can form a small pact with the user.
+
+Dream intake:
+{intake.merged_text()}
+
+Return JSON with:
+- visitor_name: short vivid name
+- questions: 2 or 3 gentle, specific, slightly weird questions
+- tone_note: one sentence explaining the visitor without certainty
+""".strip()
+
+
+def pact_prompt(intake: DreamIntake, answers: str) -> str:
+    return f"""
+You are the Dream Customs diplomat. Generate a final Today's Pact card.
+Do not diagnose. Do not claim the dream has one certain meaning.
+Give one practical next-day suggestion and one weird task doable in 5 minutes.
+
+Dream intake:
+{intake.merged_text()}
+
+User answers:
+{answers}
+
+Return strict JSON with:
+visitor_name, permit_id, contraband, risk_level, alliance_reading,
+practical_suggestion, weird_task, bedtime_release, safety_note.
+""".strip()
+```
+
+- [ ] **Step 2: Commit prompts**
+
+```bash
+git add dream_customs/prompts.py
+git commit -m "feat: add dream customs prompts"
+```
+
+## Task 5: HTML Renderer
+
+**Files:**
+- Create: `dream_customs/render.py`
+- Create: `tests/test_render.py`
+
+- [ ] **Step 1: Write failing render tests**
+
+Write `tests/test_render.py`:
+
+```python
+from dream_customs.render import render_pact_card
+from dream_customs.schema import PactCard
+
+
+def test_render_pact_card_contains_core_fields():
+    html = render_pact_card(
+        PactCard(
+            visitor_name="Late Elevator",
+            permit_id="DC-1",
+            contraband=["unfiled anxiety"],
+            risk_level="orange",
+            alliance_reading="The dream asks for a smaller start.",
+            practical_suggestion="Open one task ten minutes early.",
+            weird_task="Write the elevator an apology note.",
+            bedtime_release="Today the elevator has docked.",
+        )
+    )
+    assert "Late Elevator" in html
+    assert "Today's Pact" in html
+    assert "<script" not in html.lower()
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+python -m pytest tests/test_render.py -q
+```
+
+Expected: FAIL with missing renderer.
+
+- [ ] **Step 3: Implement renderer**
+
+Write `dream_customs/render.py`:
+
+```python
+from html import escape
+
+from dream_customs.schema import PactCard
+
+
+def render_pact_card(card: PactCard) -> str:
+    contraband = "".join(f"<li>{escape(item)}</li>" for item in card.contraband)
+    safety = f"<p class='safety'>{escape(card.safety_note)}</p>" if card.safety_note else ""
+    return f"""
+<section class="pact-card">
+  <div class="pact-header">
+    <span>Dream Customs</span>
+    <span>{escape(card.permit_id)}</span>
+  </div>
+  <h2>Today's Pact</h2>
+  <h3>{escape(card.visitor_name)}</h3>
+  <p><strong>Risk:</strong> {escape(card.risk_level)}</p>
+  <p><strong>Alliance:</strong> {escape(card.alliance_reading)}</p>
+  <p><strong>Suggestion:</strong> {escape(card.practical_suggestion)}</p>
+  <p><strong>Weird task:</strong> {escape(card.weird_task)}</p>
+  <p><strong>Bedtime release:</strong> {escape(card.bedtime_release)}</p>
+  <div><strong>Contraband</strong><ul>{contraband}</ul></div>
+  {safety}
+</section>
+""".strip()
+```
+
+- [ ] **Step 4: Run render tests**
+
+Run:
+
+```bash
+python -m pytest tests/test_render.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit renderer**
+
+```bash
+git add dream_customs/render.py tests/test_render.py
+git commit -m "feat: render dream pact card"
+```
+
+## Task 6: Fake Model Clients And Pipeline
+
+**Files:**
+- Create: `dream_customs/models.py`
+- Create: `dream_customs/pipeline.py`
+- Create: `tests/test_pipeline.py`
+
+- [ ] **Step 1: Write failing pipeline tests**
+
+Write `tests/test_pipeline.py`:
+
+```python
+from dream_customs.models import FakeTextClient, FakeVisionClient
+from dream_customs.pipeline import build_intake, generate_pact
+
+
+def test_build_intake_merges_modalities():
+    intake = build_intake(
+        dream_text="I missed an elevator.",
+        voice_transcript="The buttons melted.",
+        visual_clues=["blue hallway"],
+        mood="anxious",
+    )
+    assert "elevator" in intake.merged_text()
+    assert "blue hallway" in intake.merged_text()
+
+
+def test_generate_pact_returns_card_and_html():
+    intake = build_intake(dream_text="I missed an elevator.", mood="anxious")
+    card, html = generate_pact(intake, "I want a small start.", FakeTextClient())
+    assert card.visitor_name
+    assert "Today's Pact" in html
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+python -m pytest tests/test_pipeline.py -q
+```
+
+Expected: FAIL with missing modules.
+
+- [ ] **Step 3: Implement fake model clients**
+
+Write `dream_customs/models.py`:
+
+```python
+from dream_customs.schema import PactCard
+
+
+class FakeVisionClient:
+    def extract_clues(self, image_path: str | None) -> list[str]:
+        if not image_path:
+            return []
+        return ["blue hallway", "melted elevator buttons", "number 14"]
+
+
+class FakeTextClient:
+    def generate_pact(self, prompt: str) -> PactCard:
+        return PactCard(
+            visitor_name="Late Elevator",
+            permit_id="DC-DEMO-014",
+            contraband=["unfiled anxiety", "melted buttons"],
+            risk_level="orange: needs placement, not fear",
+            alliance_reading="This visitor asks you to separate starting from finishing.",
+            practical_suggestion="Open one small task ten minutes early.",
+            weird_task="Write the elevator a one-sentence apology note.",
+            bedtime_release="Today the elevator has docked; unfinished floors report tomorrow.",
+        )
+```
+
+- [ ] **Step 4: Implement pipeline**
+
+Write `dream_customs/pipeline.py`:
+
+```python
+from dream_customs.prompts import pact_prompt
+from dream_customs.render import render_pact_card
+from dream_customs.safety import needs_escalation, safety_note
+from dream_customs.schema import DreamIntake, PactCard
+
+
+def build_intake(
+    dream_text: str = "",
+    voice_transcript: str = "",
+    visual_clues: list[str] | None = None,
+    mood: str = "",
+    recurring_symbols: list[str] | None = None,
+    uncertainty: str = "",
+    user_context: str = "",
+) -> DreamIntake:
+    return DreamIntake(
+        dream_text=dream_text,
+        voice_transcript=voice_transcript,
+        visual_clues=visual_clues or [],
+        mood=mood,
+        recurring_symbols=recurring_symbols or [],
+        uncertainty=uncertainty,
+        user_context=user_context,
+    )
+
+
+def generate_pact(intake: DreamIntake, answers: str, text_client) -> tuple[PactCard, str]:
+    prompt = pact_prompt(intake, answers)
+    card = text_client.generate_pact(prompt)
+    merged = intake.merged_text() + "\n" + answers
+    if needs_escalation(merged):
+        card.safety_note = safety_note()
+    return card, render_pact_card(card)
+```
+
+- [ ] **Step 5: Run pipeline tests**
+
+Run:
+
+```bash
+python -m pytest tests/test_pipeline.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit pipeline**
+
+```bash
+git add dream_customs/models.py dream_customs/pipeline.py tests/test_pipeline.py
+git commit -m "feat: add dream customs pipeline"
+```
+
+## Task 7: Gradio App
+
+**Files:**
+- Create: `app.py`
+
+- [ ] **Step 1: Implement Gradio UI with fake clients**
+
+Write `app.py`:
+
+```python
+import gradio as gr
+
+from dream_customs.models import FakeTextClient, FakeVisionClient
+from dream_customs.pipeline import build_intake, generate_pact
+
+
+vision_client = FakeVisionClient()
+text_client = FakeTextClient()
+
+
+def run_customs(dream_text, image, audio, mood):
+    visual_clues = vision_client.extract_clues(image)
+    voice_transcript = ""
+    if audio:
+        voice_transcript = "Audio received. ASR adapter will transcribe this in the next implementation pass."
+    intake = build_intake(
+        dream_text=dream_text or "",
+        voice_transcript=voice_transcript,
+        visual_clues=visual_clues,
+        mood=mood or "",
+        user_context="User wants a gentle next-day suggestion after vivid dreams.",
+    )
+    card, html = generate_pact(intake, "User accepted a small pact.", text_client)
+    return intake.model_dump(), card.to_plain_text(), html
+
+
+with gr.Blocks(title="Dream Customs") as demo:
+    gr.Markdown("# Dream Customs / 梦境海关")
+    gr.Markdown("Declare last night's dream by text, image, or voice. Get a playful pact for today.")
+    with gr.Row():
+        dream_text = gr.Textbox(label="Dream text", lines=6)
+        image = gr.Image(label="Dream sketch or bedside note", type="filepath")
+        audio = gr.Audio(label="Voice note", type="filepath")
+    mood = gr.Textbox(label="Wake-up mood", placeholder="anxious, amused, foggy...")
+    submit = gr.Button("Submit to Customs")
+    intake_json = gr.JSON(label="Dream Intake")
+    plain = gr.Textbox(label="Plain text result", lines=10)
+    card = gr.HTML(label="Today's Pact Card")
+    submit.click(run_customs, [dream_text, image, audio, mood], [intake_json, plain, card])
+
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+- [ ] **Step 2: Run app smoke test**
+
+Run:
+
+```bash
+python app.py
+```
+
+Expected: local Gradio URL appears and the app loads.
+
+- [ ] **Step 3: Commit Gradio app**
+
+```bash
+git add app.py
+git commit -m "feat: add dream customs gradio app"
+```
+
+## Task 8: Real Model Adapter Pass
+
+**Files:**
+- Modify: `dream_customs/models.py`
+- Modify: `requirements.txt`
+- Add tests only if wrappers can be mocked without downloading models.
+
+- [ ] **Step 1: Add interface classes without loading models at import time**
+
+Modify `dream_customs/models.py` to add lazy classes:
+
+```python
+class MiniCPMVisionClient:
+    def __init__(self, model_name: str = "openbmb/MiniCPM-V-4.6"):
+        self.model_name = model_name
+        self._pipe = None
+
+    def _load(self):
+        if self._pipe is None:
+            from transformers import pipeline
+            self._pipe = pipeline("image-text-to-text", model=self.model_name)
+        return self._pipe
+
+    def extract_clues(self, image_path: str | None) -> list[str]:
+        if not image_path:
+            return []
+        pipe = self._load()
+        messages = [{
+            "role": "user",
+            "content": [
+                {"type": "image", "path": image_path},
+                {"type": "text", "text": "Extract concise dream-like visual clues as a comma-separated list. Do not diagnose."},
+            ],
+        }]
+        result = pipe(text=messages)
+        text = str(result)
+        return [part.strip() for part in text.replace("\n", ",").split(",") if part.strip()][:8]
+```
+
+- [ ] **Step 2: Keep fake clients as default for tests**
+
+Do not make real models load during pytest. The Gradio app may keep fake clients until model runtime is validated.
+
+- [ ] **Step 3: Commit adapters**
+
+```bash
+git add dream_customs/models.py requirements.txt
+git commit -m "feat: add minicpm model adapter skeleton"
+```
+
+## Task 9: Space Packaging And Final Checks
+
+**Files:**
+- Modify: `README.md`
+- Create: `.gitignore`
+
+- [ ] **Step 1: Add `.gitignore`**
+
+Write `.gitignore`:
+
+```text
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+.DS_Store
+.superpowers/
+```
+
+- [ ] **Step 2: Run all tests**
+
+Run:
+
+```bash
+python -m pytest -q
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 3: Run app**
+
+Run:
+
+```bash
+python app.py
+```
+
+Expected: app launches; submit sample dream; final card renders.
+
+- [ ] **Step 4: Commit final packaging**
+
+```bash
+git add .gitignore README.md
+git commit -m "chore: prepare dream customs space packaging"
+```
+
+## Self-Review
+
+- Spec coverage: text, image, voice, DreamIntake, MiniCPM roles, safety, card output, and Gradio are covered.
+- Placeholder scan: no planned step uses unresolved placeholder tokens as an implementation substitute.
+- Type consistency: `DreamIntake`, `PactCard`, `FakeTextClient`, and `FakeVisionClient` are defined before use.
+
+## Execution Choice
+
+Plan complete and saved to `docs/superpowers/plans/2026-06-05-dream-customs-mvp.md`.
+
+Recommended execution option: Subagent-Driven. Use one fresh worker per task, review between tasks, and keep commits small.

dream_customs/__init__.py

@@ -0,0 +1 @@
+"""Dream Customs package."""

dream_customs/app_logic.py

@@ -0,0 +1,102 @@
+import json
+import os
+from typing import Any, Tuple
+
+from dream_customs.models import (
+    FakeASRClient,
+    FakeTextClient,
+    FakeVisionClient,
+    OllamaTextClient,
+    OllamaVisionClient,
+)
+from dream_customs.pipeline import generate_negotiation, generate_pact, intake_from_modalities
+
+
+DEFAULT_TEXT_MODEL = "hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0"
+DEFAULT_VISION_MODEL = "openbmb/minicpm-v4.6"
+
+
+def _file_path(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        return str(value.get("path") or value.get("name") or "")
+    if isinstance(value, (list, tuple)) and value:
+        return _file_path(value[0])
+    return ""
+
+
+def _clients(text_backend: str, vision_backend: str):
+    text_backend = (text_backend or "demo").lower()
+    vision_backend = (vision_backend or "demo").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"),
+        )
+    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"),
+        )
+    else:
+        vision_client = FakeVisionClient()
+
+    return text_client, vision_client, FakeASRClient()
+
+
+def run_customs_once(
+    dream_text: str,
+    image_value: Any = None,
+    audio_value: Any = None,
+    mood: str = "",
+    answers: str = "",
+    text_backend: str = "demo",
+    vision_backend: str = "demo",
+) -> Tuple[str, str, str, str]:
+    image_path = _file_path(image_value)
+    audio_path = _file_path(audio_value)
+    if not any([dream_text and dream_text.strip(), image_path, audio_path]):
+        return (
+            "No declaration received.",
+            "Please add text, an image, or a voice note before requesting clearance.",
+            "",
+            json.dumps({"status": "empty"}, ensure_ascii=False, indent=2),
+        )
+
+    text_client, vision_client, asr_client = _clients(text_backend, vision_backend)
+    intake = intake_from_modalities(
+        dream_text=dream_text or "",
+        image_path=image_path or None,
+        audio_path=audio_path or None,
+        mood=mood or "",
+        vision_client=vision_client,
+        asr_client=asr_client,
+    )
+    negotiation = generate_negotiation(intake, text_client)
+    answer_text = answers or "The user has not answered yet; infer a gentle pact from the declaration."
+    card, html = generate_pact(intake, answer_text, text_client)
+    questions = "\n".join(f"{index}. {question}" for index, question in enumerate(negotiation["questions"], start=1))
+    negotiation_text = "\n".join(
+        part
+        for part in [
+            f"Visitor: {negotiation['visitor_name']}",
+            questions,
+            negotiation.get("tone_note", ""),
+        ]
+        if part
+    )
+    debug = {
+        "status": "ok",
+        "text_backend": text_backend,
+        "vision_backend": vision_backend,
+        "intake": intake.model_dump(),
+        "negotiation": negotiation,
+        "pact": card.model_dump(),
+    }
+    return negotiation_text, card.to_plain_text(), html, json.dumps(debug, ensure_ascii=False, indent=2)

dream_customs/models.py

@@ -0,0 +1,302 @@
+import base64
+import json
+import re
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from dream_customs.prompts import visual_clue_prompt
+from dream_customs.schema import PactCard
+
+
+def _contains_cjk(text: str) -> bool:
+    return bool(re.search(r"[\u4e00-\u9fff]", text))
+
+
+class FakeVisionClient:
+    def extract_clues(self, image_path: Optional[str]) -> List[str]:
+        if not image_path:
+            return []
+        return ["blue hallway", "melted elevator buttons", "number 14"]
+
+
+class FakeASRClient:
+    def transcribe(self, audio_path: Optional[str]) -> str:
+        if not audio_path:
+            return ""
+        return "The buttons melted and I could not catch the elevator."
+
+
+class FakeTextClient:
+    def generate_negotiation(self, prompt: str) -> Dict[str, Any]:
+        if _contains_cjk(prompt):
+            return {
+                "visitor_name": "迟到的电梯",
+                "questions": [
+                    "这部电梯是在阻止你，还是在替你争取一点慢下来的时间？",
+                    "如果它今天只允许你带走一件东西，你会选择哪件未完成的小事？",
+                    "你愿意用一个 5 分钟动作和它交换放行章吗？",
+                ],
+                "tone_note": "这个来访者也许不是敌人，而是在提醒你把开始和完成分开。",
+            }
+        return {
+            "visitor_name": "Late Elevator",
+            "questions": [
+                "Was the elevator blocking you, or buying you a slower morning?",
+                "If it lets you carry one unfinished thing into today, which one is smallest?",
+                "Would you trade it a five-minute action for a release stamp?",
+            ],
+            "tone_note": "This visitor may be asking you to separate starting from finishing.",
+        }
+
+    def generate_pact(self, prompt: str) -> PactCard:
+        if _contains_cjk(prompt):
+            return PactCard(
+                visitor_name="迟到的电梯",
+                permit_id="DC-DEMO-014",
+                contraband=["未申报的焦虑", "融化的按钮", "一小袋没来得及开始的事"],
+                risk_level="橙色：需要被安置，但不需要被害怕",
+                alliance_reading="这个梦也许在提醒你，今天先把启动一件事和完成一件事分开。",
+                practical_suggestion="提前 10 分钟打开一个最小任务，只要求开始，不要求完成。",
+                weird_task="给电梯写一句道歉信：抱歉总让你替我背迟到的锅。",
+                bedtime_release="今日电梯已停靠，未完成事项明日再报关。",
+            )
+        return PactCard(
+            visitor_name="Late Elevator",
+            permit_id="DC-DEMO-014",
+            contraband=["unfiled anxiety", "melted buttons", "one pouch of unstarted tasks"],
+            risk_level="orange: needs placement, not fear",
+            alliance_reading="This visitor asks you to separate starting from finishing.",
+            practical_suggestion="Open one small task ten minutes early. You only need to start it.",
+            weird_task="Write the elevator a one-sentence apology note.",
+            bedtime_release="Today the elevator has docked; unfinished floors report tomorrow.",
+        )
+
+
+def _strip_markdown_and_thinking(text: str) -> str:
+    cleaned = text.strip()
+    cleaned = re.sub(r"<think>.*?</think>", "", cleaned, flags=re.DOTALL).strip()
+    cleaned = cleaned.replace("<think>", "").replace("</think>", "").strip()
+    if cleaned.startswith("```"):
+        cleaned = re.sub(r"^```(?:json)?", "", cleaned.strip(), flags=re.IGNORECASE).strip()
+        cleaned = re.sub(r"```$", "", cleaned).strip()
+    return cleaned
+
+
+def _extract_json_object(text: str) -> Optional[Dict[str, Any]]:
+    cleaned = _strip_markdown_and_thinking(text)
+    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 _as_string_list(value: Any) -> List[str]:
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    if isinstance(value, str) and value.strip():
+        return [part.strip() for part in re.split(r"[,，\n]", value) if part.strip()]
+    return []
+
+
+class OllamaTextClient:
+    def __init__(
+        self,
+        model_name: str = "hf.co/openbmb/MiniCPM5-1B-GGUF:Q8_0",
+        base_url: str = "http://localhost:11434",
+        timeout: float = 45.0,
+        fallback: Optional[FakeTextClient] = None,
+    ):
+        self.model_name = model_name
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.fallback = fallback or FakeTextClient()
+
+    def _post_generate(self, prompt: str, num_predict: int = 512) -> Dict[str, Any]:
+        payload = {
+            "model": self.model_name,
+            "prompt": prompt,
+            "stream": False,
+            "options": {"temperature": 0.2, "num_predict": num_predict},
+        }
+        data = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.base_url}/api/generate",
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    def _generate_json(self, prompt: str, schema_hint: str, num_predict: int = 512) -> Optional[Dict[str, Any]]:
+        strict_prompt = (
+            f"{prompt}\n\n"
+            "Return only a single valid JSON object. No markdown, no code fences, no hidden reasoning.\n"
+            f"Required schema: {schema_hint}"
+        )
+        try:
+            response = self._post_generate(strict_prompt, num_predict=num_predict)
+        except (OSError, TimeoutError, urllib.error.URLError, json.JSONDecodeError):
+            return None
+        return _extract_json_object(str(response.get("response", "")))
+
+    def generate_negotiation(self, prompt: str) -> Dict[str, Any]:
+        parsed = self._generate_json(
+            prompt,
+            '{"visitor_name":"string","questions":["string","string"],"tone_note":"string"}',
+            num_predict=320,
+        )
+        if not parsed:
+            return self.fallback.generate_negotiation(prompt)
+        questions = _as_string_list(parsed.get("questions"))
+        if not parsed.get("visitor_name") or not questions:
+            return self.fallback.generate_negotiation(prompt)
+        return {
+            "visitor_name": str(parsed.get("visitor_name", "")).strip(),
+            "questions": questions[:3],
+            "tone_note": str(parsed.get("tone_note", "")).strip(),
+        }
+
+    def generate_pact(self, prompt: str) -> PactCard:
+        parsed = self._generate_json(
+            prompt,
+            (
+                '{"visitor_name":"string","permit_id":"string","contraband":["string"],'
+                '"risk_level":"string","alliance_reading":"string","practical_suggestion":"string",'
+                '"weird_task":"string","bedtime_release":"string","safety_note":"string"}'
+            ),
+            num_predict=700,
+        )
+        if not parsed:
+            return self.fallback.generate_pact(prompt)
+        try:
+            return PactCard(
+                visitor_name=str(parsed["visitor_name"]).strip(),
+                permit_id=str(parsed["permit_id"]).strip(),
+                contraband=_as_string_list(parsed["contraband"]) or ["unfiled dream fragment"],
+                risk_level=str(parsed["risk_level"]).strip(),
+                alliance_reading=str(parsed["alliance_reading"]).strip(),
+                practical_suggestion=str(parsed["practical_suggestion"]).strip(),
+                weird_task=str(parsed["weird_task"]).strip(),
+                bedtime_release=str(parsed["bedtime_release"]).strip(),
+                safety_note=str(parsed.get("safety_note", "")).strip(),
+            )
+        except (KeyError, TypeError, ValueError):
+            return self.fallback.generate_pact(prompt)
+
+
+class OllamaVisionClient:
+    def __init__(
+        self,
+        model_name: str = "openbmb/minicpm-v4.6",
+        base_url: str = "http://localhost:11434",
+        timeout: float = 60.0,
+    ):
+        self.model_name = model_name
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _post_generate(self, prompt: str, image_b64: str, num_predict: int = 256) -> Dict[str, Any]:
+        payload = {
+            "model": self.model_name,
+            "prompt": prompt,
+            "images": [image_b64],
+            "stream": False,
+            "options": {"temperature": 0.1, "num_predict": num_predict},
+        }
+        data = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.base_url}/api/generate",
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    def extract_clues(self, image_path: Optional[str]) -> List[str]:
+        if not image_path:
+            return []
+        try:
+            with open(image_path, "rb") as image_file:
+                image_b64 = base64.b64encode(image_file.read()).decode("ascii")
+            response = self._post_generate(visual_clue_prompt(), image_b64)
+        except (OSError, TimeoutError, urllib.error.URLError, json.JSONDecodeError):
+            return []
+
+        text = str(response.get("response", ""))
+        parsed = _extract_json_object(text)
+        if parsed:
+            clues: List[str] = []
+            for key in ("objects", "places", "visible_text", "colors", "mood_cues", "uncertain_details"):
+                clues.extend(_as_string_list(parsed.get(key)))
+            return clues[:8]
+        return [part.strip() for part in re.split(r"[,，\n]", _strip_markdown_and_thinking(text)) if part.strip()][:8]
+
+
+class MiniCPMVisionClient:
+    def __init__(self, model_name: str = "openbmb/MiniCPM-V-4.6"):
+        self.model_name = model_name
+        self._pipe = None
+
+    def _load(self):
+        if self._pipe is None:
+            from transformers import pipeline
+
+            self._pipe = pipeline("image-text-to-text", model=self.model_name)
+        return self._pipe
+
+    def extract_clues(self, image_path: Optional[str]) -> List[str]:
+        if not image_path:
+            return []
+        pipe = self._load()
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "path": image_path},
+                    {
+                        "type": "text",
+                        "text": (
+                            "Extract concise dream-like visual clues from this image. "
+                            "Return a comma-separated list. Do not diagnose."
+                        ),
+                    },
+                ],
+            }
+        ]
+        result = pipe(text=messages)
+        text = str(result)
+        return [part.strip() for part in text.replace("\n", ",").split(",") if part.strip()][:8]

dream_customs/pipeline.py

@@ -0,0 +1,58 @@
+from typing import Dict, List, Optional, Tuple
+
+from dream_customs.prompts import negotiation_prompt, pact_prompt
+from dream_customs.render import render_pact_card
+from dream_customs.safety import needs_escalation, safety_note
+from dream_customs.schema import DreamIntake, PactCard
+
+
+def build_intake(
+    dream_text: str = "",
+    voice_transcript: str = "",
+    visual_clues: Optional[List[str]] = None,
+    mood: str = "",
+    recurring_symbols: Optional[List[str]] = None,
+    uncertainty: str = "",
+    user_context: str = "",
+) -> DreamIntake:
+    return DreamIntake(
+        dream_text=dream_text,
+        voice_transcript=voice_transcript,
+        visual_clues=visual_clues or [],
+        mood=mood,
+        recurring_symbols=recurring_symbols or [],
+        uncertainty=uncertainty,
+        user_context=user_context,
+    )
+
+
+def intake_from_modalities(
+    dream_text: str,
+    image_path: Optional[str],
+    audio_path: Optional[str],
+    mood: str,
+    vision_client,
+    asr_client,
+    user_context: str = "User wants a gentle next-day suggestion after vivid dreams.",
+) -> DreamIntake:
+    return build_intake(
+        dream_text=dream_text or "",
+        voice_transcript=asr_client.transcribe(audio_path),
+        visual_clues=vision_client.extract_clues(image_path),
+        mood=mood or "",
+        user_context=user_context,
+    )
+
+
+def generate_negotiation(intake: DreamIntake, text_client) -> Dict:
+    prompt = negotiation_prompt(intake)
+    return text_client.generate_negotiation(prompt)
+
+
+def generate_pact(intake: DreamIntake, answers: str, text_client) -> Tuple[PactCard, str]:
+    prompt = pact_prompt(intake, answers)
+    card = text_client.generate_pact(prompt)
+    merged = intake.merged_text() + "\n" + answers
+    if needs_escalation(merged):
+        card.safety_note = safety_note()
+    return card, render_pact_card(card)

dream_customs/prompts.py

@@ -0,0 +1,45 @@
+from dream_customs.schema import DreamIntake
+
+
+def visual_clue_prompt() -> str:
+    return (
+        "You are the witness clerk at Dream Customs. Extract concise visual clues "
+        "from this dream sketch, note, screenshot, or photo. Return JSON with keys: "
+        "objects, places, visible_text, colors, mood_cues, uncertain_details. "
+        "Do not diagnose the user."
+    )
+
+
+def negotiation_prompt(intake: DreamIntake) -> str:
+    return f"""
+You are the Dream Customs diplomat. The user is not asking for diagnosis.
+Treat the dream as a strange visitor that can form a small pact with the user.
+The tone should be gentle, playful, and specific. Do not make medical claims.
+
+Dream intake:
+{intake.merged_text()}
+
+Return JSON with:
+- visitor_name: short vivid name
+- questions: 2 or 3 gentle, specific, slightly weird questions
+- tone_note: one sentence explaining the visitor without certainty
+""".strip()
+
+
+def pact_prompt(intake: DreamIntake, answers: str) -> str:
+    return f"""
+You are the Dream Customs diplomat. Generate a final Today's Pact card.
+Do not diagnose. Do not claim the dream has one certain meaning.
+Give one practical next-day suggestion and one weird task doable in 5 minutes.
+Use warm, non-clinical language. If the user wrote in Chinese, answer in Chinese.
+
+Dream intake:
+{intake.merged_text()}
+
+User answers:
+{answers}
+
+Return strict JSON with:
+visitor_name, permit_id, contraband, risk_level, alliance_reading,
+practical_suggestion, weird_task, bedtime_release, safety_note.
+""".strip()

dream_customs/render.py

@@ -0,0 +1,78 @@
+from html import escape
+
+from dream_customs.schema import PactCard
+
+
+def render_pact_card(card: PactCard) -> str:
+    contraband = "".join(f"<li>{escape(item)}</li>" for item in card.contraband)
+    safety = f"<p class='dc-safety'>{escape(card.safety_note)}</p>" if card.safety_note else ""
+    return f"""
+<style>
+  .pact-card {{
+    color: #102c3a;
+    background: linear-gradient(135deg, #fff8ea 0%, #e8f4ef 100%);
+    border: 3px solid #102c3a;
+    border-radius: 10px;
+    box-shadow: 10px 10px 0 rgba(16, 44, 58, 0.14);
+    font-family: Georgia, 'Songti SC', serif;
+    line-height: 1.55;
+    margin: 8px 0;
+    max-width: 860px;
+    padding: 24px;
+  }}
+  .pact-header {{
+    align-items: center;
+    border-bottom: 2px dashed rgba(16, 44, 58, 0.25);
+    display: flex;
+    font-weight: 800;
+    justify-content: space-between;
+    margin-bottom: 16px;
+    padding-bottom: 10px;
+  }}
+  .pact-card h2 {{
+    font-size: 32px;
+    line-height: 1.1;
+    margin: 0 0 4px;
+  }}
+  .pact-card h3 {{
+    color: #e85d4f;
+    font-size: 24px;
+    margin: 0 0 18px;
+  }}
+  .dc-label {{
+    color: #36545c;
+    font-weight: 800;
+  }}
+  .dc-seal {{
+    border: 3px solid #e85d4f;
+    border-radius: 999px;
+    color: #e85d4f;
+    display: inline-block;
+    font-weight: 900;
+    margin-top: 12px;
+    padding: 8px 14px;
+    transform: rotate(-4deg);
+  }}
+  .dc-safety {{
+    background: rgba(232, 93, 79, 0.11);
+    border-left: 4px solid #e85d4f;
+    padding: 10px 12px;
+  }}
+</style>
+<section class="pact-card">
+  <div class="pact-header">
+    <span>Dream Customs</span>
+    <span>{escape(card.permit_id)}</span>
+  </div>
+  <h2>Today's Pact</h2>
+  <h3>{escape(card.visitor_name)}</h3>
+  <p><span class="dc-label">Risk:</span> {escape(card.risk_level)}</p>
+  <p><span class="dc-label">Alliance:</span> {escape(card.alliance_reading)}</p>
+  <p><span class="dc-label">Suggestion:</span> {escape(card.practical_suggestion)}</p>
+  <p><span class="dc-label">Weird task:</span> {escape(card.weird_task)}</p>
+  <p><span class="dc-label">Bedtime release:</span> {escape(card.bedtime_release)}</p>
+  <div><span class="dc-label">Contraband:</span><ul>{contraband}</ul></div>
+  {safety}
+  <span class="dc-seal">SEALED</span>
+</section>
+""".strip()

dream_customs/safety.py

@@ -0,0 +1,30 @@
+ESCALATION_TERMS = (
+    "hurt myself",
+    "kill myself",
+    "suicide",
+    "self-harm",
+    "hurt someone",
+    "many nights",
+    "cannot function",
+    "panic attack",
+    "想伤害自己",
+    "自杀",
+    "自残",
+    "伤害别人",
+    "很多天睡不着",
+    "无法正常生活",
+    "无法生活",
+)
+
+
+def needs_escalation(text: str) -> bool:
+    lowered = text.lower()
+    return any(term in lowered for term in ESCALATION_TERMS)
+
+
+def safety_note() -> str:
+    return (
+        "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."
+    )

dream_customs/schema.py

@@ -0,0 +1,51 @@
+from pydantic import BaseModel, Field
+
+
+class DreamIntake(BaseModel):
+    dream_text: str = ""
+    voice_transcript: str = ""
+    visual_clues: list[str] = Field(default_factory=list)
+    mood: str = ""
+    recurring_symbols: list[str] = Field(default_factory=list)
+    uncertainty: str = ""
+    user_context: str = ""
+
+    def merged_text(self) -> str:
+        parts = [
+            self.dream_text.strip(),
+            self.voice_transcript.strip(),
+            "Visual clues: " + ", ".join(self.visual_clues) if self.visual_clues else "",
+            "Mood: " + self.mood.strip() if self.mood else "",
+            "Recurring symbols: " + ", ".join(self.recurring_symbols) if self.recurring_symbols else "",
+            "Uncertainty: " + self.uncertainty.strip() if self.uncertainty else "",
+            "Context: " + self.user_context.strip() if self.user_context else "",
+        ]
+        return "\n".join(part for part in parts if part)
+
+
+class PactCard(BaseModel):
+    visitor_name: str
+    permit_id: str
+    contraband: list[str]
+    risk_level: str
+    alliance_reading: str
+    practical_suggestion: str
+    weird_task: str
+    bedtime_release: str
+    safety_note: str = ""
+
+    def to_plain_text(self) -> str:
+        contraband = ", ".join(self.contraband)
+        lines = [
+            f"Dream visitor: {self.visitor_name}",
+            f"Permit: {self.permit_id}",
+            f"Contraband: {contraband}",
+            f"Risk level: {self.risk_level}",
+            f"Alliance reading: {self.alliance_reading}",
+            f"Today's suggestion: {self.practical_suggestion}",
+            f"Weird task: {self.weird_task}",
+            f"Bedtime release: {self.bedtime_release}",
+        ]
+        if self.safety_note:
+            lines.append(f"Safety note: {self.safety_note}")
+        return "\n".join(lines)

requirements.txt

@@ -0,0 +1,11 @@
+gradio>=4.44,<5.0
+huggingface_hub<1.0
+pydantic>=2.7
+pytest>=8.0
+pillow
+soundfile
+
+# Optional direct Hugging Face runtime for MiniCPM-V.
+# The default local demo uses Ollama adapters or the stable demo backend.
+# transformers>=4.56
+# torch

tests/conftest.py

@@ -0,0 +1,6 @@
+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))

tests/test_app_logic.py

@@ -0,0 +1,25 @@
+import json
+
+from dream_customs.app_logic import run_customs_once
+
+
+def test_run_customs_once_generates_demo_outputs():
+    negotiation, pact_text, html, debug_json = run_customs_once(
+        dream_text="我梦见迟到的电梯。",
+        mood="foggy",
+        answers="我想先完成一件小事。",
+    )
+    debug = json.loads(debug_json)
+    assert "Visitor:" in negotiation
+    assert "Dream visitor:" in pact_text
+    assert "Today's Pact" in html
+    assert debug["status"] == "ok"
+    assert debug["intake"]["dream_text"] == "我梦见迟到的电梯。"
+
+
+def test_run_customs_once_requires_one_modality():
+    negotiation, pact_text, html, debug_json = run_customs_once(dream_text="")
+    assert negotiation == "No declaration received."
+    assert "Please add text" in pact_text
+    assert html == ""
+    assert json.loads(debug_json) == {"status": "empty"}

tests/test_ollama_models.py

@@ -0,0 +1,71 @@
+from dream_customs.models import OllamaTextClient, OllamaVisionClient, _extract_json_object
+
+
+class StubOllamaTextClient(OllamaTextClient):
+    def __init__(self, response_text: str):
+        super().__init__()
+        self.response_text = response_text
+
+    def _post_generate(self, prompt: str, num_predict: int = 512):
+        return {"response": self.response_text}
+
+
+class StubOllamaVisionClient(OllamaVisionClient):
+    def __init__(self, response_text: str):
+        super().__init__()
+        self.response_text = response_text
+
+    def _post_generate(self, prompt: str, image_b64: str, num_predict: int = 256):
+        return {"response": self.response_text}
+
+
+def test_extract_json_object_handles_code_fence():
+    parsed = _extract_json_object('```json\n{"visitor_name": "Gate 14"}\n```')
+    assert parsed == {"visitor_name": "Gate 14"}
+
+
+def test_ollama_text_client_parses_negotiation_json():
+    client = StubOllamaTextClient(
+        '{"visitor_name":"迟到的电梯","questions":["它要什么？","你要什么？"],"tone_note":"温和一点"}'
+    )
+    negotiation = client.generate_negotiation("梦见电梯")
+    assert negotiation["visitor_name"] == "迟到的电梯"
+    assert negotiation["questions"] == ["它要什么？", "你要什么？"]
+
+
+def test_ollama_text_client_falls_back_on_empty_json():
+    client = StubOllamaTextClient("{}")
+    negotiation = client.generate_negotiation("梦见电梯")
+    assert negotiation["visitor_name"]
+    assert len(negotiation["questions"]) == 3
+
+
+def test_ollama_text_client_parses_pact_card():
+    client = StubOllamaTextClient(
+        """
+        {
+          "visitor_name":"迟到的电梯",
+          "permit_id":"DC-42",
+          "contraband":["未申报的焦虑"],
+          "risk_level":"yellow",
+          "alliance_reading":"先开始，不急着完成。",
+          "practical_suggestion":"打开一个 5 分钟任务。",
+          "weird_task":"给电梯盖章。",
+          "bedtime_release":"今日放行。",
+          "safety_note":""
+        }
+        """
+    )
+    card = client.generate_pact("梦见电梯")
+    assert card.permit_id == "DC-42"
+    assert card.contraband == ["未申报的焦虑"]
+
+
+def test_ollama_vision_client_parses_visual_clues(tmp_path):
+    image_path = tmp_path / "dream.png"
+    image_path.write_bytes(b"not a real png but enough for adapter encoding")
+    client = StubOllamaVisionClient(
+        '{"objects":["passport stamp"],"places":["customs desk"],"colors":["blue"],"mood_cues":["foggy"]}'
+    )
+    clues = client.extract_clues(str(image_path))
+    assert clues == ["passport stamp", "customs desk", "blue", "foggy"]

tests/test_pipeline.py

@@ -0,0 +1,48 @@
+from dream_customs.models import FakeASRClient, FakeTextClient, FakeVisionClient
+from dream_customs.pipeline import build_intake, generate_negotiation, generate_pact, intake_from_modalities
+
+
+def test_build_intake_merges_modalities():
+    intake = build_intake(
+        dream_text="I missed an elevator.",
+        voice_transcript="The buttons melted.",
+        visual_clues=["blue hallway"],
+        mood="anxious",
+    )
+    assert "elevator" in intake.merged_text()
+    assert "blue hallway" in intake.merged_text()
+
+
+def test_intake_from_modalities_uses_adapters():
+    intake = intake_from_modalities(
+        dream_text="",
+        image_path="demo.png",
+        audio_path="demo.wav",
+        mood="foggy",
+        vision_client=FakeVisionClient(),
+        asr_client=FakeASRClient(),
+    )
+    merged = intake.merged_text()
+    assert "The buttons melted" in merged
+    assert "blue hallway" in merged
+    assert "Mood: foggy" in merged
+
+
+def test_generate_negotiation_returns_questions():
+    intake = build_intake(dream_text="I missed an elevator.", mood="anxious")
+    negotiation = generate_negotiation(intake, FakeTextClient())
+    assert negotiation["visitor_name"]
+    assert len(negotiation["questions"]) == 3
+
+
+def test_generate_pact_returns_card_and_html():
+    intake = build_intake(dream_text="I missed an elevator.", mood="anxious")
+    card, html = generate_pact(intake, "I want a small start.", FakeTextClient())
+    assert card.visitor_name
+    assert "Today's Pact" in html
+
+
+def test_generate_pact_adds_safety_note_for_distress():
+    intake = build_intake(dream_text="I might hurt myself if I cannot sleep.")
+    card, _html = generate_pact(intake, "", FakeTextClient())
+    assert card.safety_note

tests/test_render.py

@@ -0,0 +1,37 @@
+from dream_customs.render import render_pact_card
+from dream_customs.schema import PactCard
+
+
+def test_render_pact_card_contains_core_fields():
+    html = render_pact_card(
+        PactCard(
+            visitor_name="Late Elevator",
+            permit_id="DC-1",
+            contraband=["unfiled anxiety"],
+            risk_level="orange",
+            alliance_reading="The dream asks for a smaller start.",
+            practical_suggestion="Open one task ten minutes early.",
+            weird_task="Write the elevator an apology note.",
+            bedtime_release="Today the elevator has docked.",
+        )
+    )
+    assert "Late Elevator" in html
+    assert "Today's Pact" in html or "Today's Pact" in html
+    assert "<script" not in html.lower()
+
+
+def test_render_pact_card_escapes_user_like_content():
+    html = render_pact_card(
+        PactCard(
+            visitor_name="<bad>",
+            permit_id="DC-2",
+            contraband=["<script>alert(1)</script>"],
+            risk_level="green",
+            alliance_reading="Maybe this visitor wants a smaller morning.",
+            practical_suggestion="Drink water.",
+            weird_task="Salute the kettle.",
+            bedtime_release="The kettle is released.",
+        )
+    )
+    assert "<bad>" not in html
+    assert "<script" not in html.lower()

tests/test_safety.py

@@ -0,0 +1,17 @@
+from dream_customs.safety import needs_escalation, safety_note
+
+
+def test_ordinary_dream_does_not_escalate():
+    assert not needs_escalation("I dreamed about a strange elevator.")
+
+
+def test_self_harm_text_escalates():
+    assert needs_escalation("I might hurt myself if I cannot sleep.")
+
+
+def test_chinese_severe_insomnia_escalates():
+    assert needs_escalation("我已经很多天睡不着，感觉无法正常生活。")
+
+
+def test_safety_note_mentions_professional_support():
+    assert "professional support" in safety_note().lower()

tests/test_schema.py

@@ -0,0 +1,39 @@
+from dream_customs.schema import DreamIntake, PactCard
+
+
+def test_dream_intake_defaults_lists():
+    intake = DreamIntake(dream_text="I missed an elevator.")
+    assert intake.dream_text == "I missed an elevator."
+    assert intake.visual_clues == []
+    assert intake.recurring_symbols == []
+
+
+def test_dream_intake_merged_text_includes_modalities():
+    intake = DreamIntake(
+        dream_text="I missed an elevator.",
+        voice_transcript="The buttons melted.",
+        visual_clues=["blue hallway"],
+        mood="anxious",
+        recurring_symbols=["elevator"],
+        user_context="I slept badly.",
+    )
+    merged = intake.merged_text()
+    assert "I missed an elevator." in merged
+    assert "The buttons melted." in merged
+    assert "blue hallway" in merged
+    assert "Mood: anxious" in merged
+
+
+def test_pact_card_requires_core_fields():
+    card = PactCard(
+        visitor_name="Late Elevator",
+        permit_id="DC-0001",
+        contraband=["unfiled anxiety"],
+        risk_level="orange",
+        alliance_reading="The dream asks for a smaller start.",
+        practical_suggestion="Open one task ten minutes early.",
+        weird_task="Write the elevator an apology note.",
+        bedtime_release="Today the elevator has docked.",
+    )
+    assert card.safety_note == ""
+    assert "Late Elevator" in card.to_plain_text()