# Dream QA / 梦境问答台 Handoff

Last updated: 2026-06-08

## 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 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. 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 `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 `model` for both text and vision backends, so a configured Space calls Modal immediately. The `demo` backend remains available in developer settings as the deterministic fallback path.

The public Space can run on ZeroGPU after `dream_customs.zerogpu` registers the lightweight `@spaces.GPU` startup probe. Modal credits still pay for the hidden 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.

## Open Questions For User

These do not block document alignment:

- Which ASR adapter is acceptable for the hackathon submission?
- Should `refs/pr/*` cleanup be done after HF Space merges, or left for auditability?