# Dream QA / 梦境问答台 Handoff Last updated: 2026-06-14 ## Current Product Direction The project is pivoting from a customs/pact-centered ritual into a step-by-step dream Q&A Gradio app. The repo and Space still use the `Dream Customs` name for continuity, but future product work should use the `Dream QA / 梦境问答台` direction: > 输入梦境，回答或跳过几个温和追问，最后得到一个和梦境细节相关的今日小 Tips。 The public hackathon experience is English-first. Keep the visible `English / 中文` toggle so Chinese remains a first-class path, but do not make judges land on a Chinese-only first screen. ## Deprecated Context Earlier implementation and smoke docs mention: - dream visitor - customs negotiation - permit ID - contraband - sealed pact - bedtime release Those are historical context, not the new target. Do not build new work around permit/contraband/sealed-pact unless the user explicitly reverses this pivot. ## Current Source Documents Read in this order: 1. `AGENTS.md` 2. `docs/spec.md` 3. `docs/prd.md` 4. `PRODUCT.md` 5. `DESIGN.md` 6. `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md` 7. `docs/superpowers/plans/2026-06-08-dream-qa-refactor-doc-plan.md` Prototype references: - `docs/prototypes/2026-06-08-dream-qa-mobile-flow.png` - `docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png` - `docs/prototypes/2026-06-08-dream-qa-tips-card.png` ## Product Decision Build a guided dream interpretation app, not a diagnosis app, not a fortune-telling app, and not a one-shot pact generator. Final positioning: > Dream QA helps you record a dream, answer or skip one gentle question, and leave with one grounded Morning Ticket whose first payload is a Today Tip. 2026-06-09 tone contract: - English mode is not just English UI chrome; generated anchors, questions, and Today Tips should read as natural English. - If the model receives Chinese anchors while the selected language is English, translate or paraphrase them unless a short exact quote is intentionally preserved. - Tiny actions should feel like five-minute first steps. Avoid urgent command phrasing such as "address it immediately." - The final card should show the Today Tip before interpretation; interpretation is supporting reflection and should use the user's answer when it names a real task. ## Model Decision Use: - `openbmb/MiniCPM-V-4.6` for image/sketch/note understanding. - `openbmb/MiniCPM5-1B` for text reasoning, follow-up questions, interpretation, and final Today Tip. 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. The submitted route uses `XiaomiMiMo/MiMo-V2.5-ASR` only for transcription; dream understanding and final generation stay 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 `DreamQuestionIntake`. 5. MiniCPM5-1B creates a short dream summary and identifies the user's likely main question. 6. MiniCPM5-1B asks 1-3 gentle follow-up questions. 7. User answers, skips, adds detail, or asks for another angle. 8. MiniCPM5-1B drafts a grounded interpretation. 9. MiniCPM5-1B generates a final `TodayTipCard`. 10. Gradio renders a mobile-readable result card and plain text. Language behavior: - Default: English. - Toggle: `中文`. - The same intake/state/card pipeline serves both languages. - MiniCPM prompts should instruct the selected output language instead of duplicating the product flow. ## Required Output Fields - `dream_summary` - `main_question` - `dream_anchors` - `followup_questions` - `user_answers` - `interpretation` - `today_tip` - `tiny_action` - `caring_note` - `safety_note` The final `today_tip` must reference at least one concrete dream anchor. Generic wellness advice is a regression. ## 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 Implementation Scope The existing package should be refactored rather than replaced from scratch: ```text app.py requirements.txt README.md dream_customs/ __init__.py schema.py prompts.py safety.py render.py pipeline.py models.py ui/ tests/ ``` Likely code files to change: - `dream_customs/schema.py` - `dream_customs/prompts.py` - `dream_customs/pipeline.py` - `dream_customs/render.py` - `dream_customs/ui/actions.py` - `dream_customs/ui/app.py` - `dream_customs/ui/copy.py` - `dream_customs/ui/styles.py` - tests covering schema, prompts, pipeline, render, UI actions, and safety ## Implementation Priorities 1. Preserve text-only demo fallback. 2. Replace pact schema with Q&A state and Today Tip output. 3. Preserve image and voice as optional evidence in the same intake. 4. Make follow-up questions a first-class user action. 5. Render one clear final tip, not a multi-field customs certificate. 6. Keep mobile readability. 7. Run tests and local Gradio smoke before any Space sync. 8. Run `python scripts/evaluate_today_tip_quality.py` before deployment. ## Repository Status This directory is a dedicated Dream Customs/Dream QA repository: - Local path: `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon` - GitHub remote: `https://github.com/adjcjh777/dream-customs-build-small.git` - Hugging Face Space remote: `https://huggingface.co/spaces/build-small-hackathon/dream-customs` Continue to confirm `git remote -v` before pushing. ## Modal Backend Route The intended production-quality route remains: ```text Hugging Face Space Gradio UI -> HostedMiniCPMTextClient / HostedMiniCPMVisionClient -> private Modal endpoints -> MiniCPM5-1B text generation and MiniCPM-V-4.6 visual clue extraction ``` The Space defaults to `modal` for text, vision, and voice transcription backends, so a configured Space enters the private Modal routes first. The `model` auto route remains available for compatibility, and the `demo` backend remains available in developer settings as the deterministic fallback path. The public Space can run on ZeroGPU after `dream_customs.zerogpu` registers the lightweight `@spaces.GPU` startup probe. Modal credits still pay for the hidden GPU backend; the ZeroGPU probe is only there to make the HF hardware setting valid for this Gradio frontend. ## Resolved Decisions - Public UI name: `Dream QA`, with `Dream Customs` retained as project/Space continuity. - Language: English-first for the international hackathon, with Chinese available through an in-app toggle. - Recommendation quality: deterministic Today Tip eval is required before deployment. ## Final Submission Notes - Text and image are the recommended public demo path. - Voice is implemented through MiMo ASR and should be presented as optional until live transcription success is consistently proven. - Leave old `refs/pr/*` discussion refs in place unless cleanup is explicitly requested; they are useful audit history for the final hackathon push.