Hugging Face's logo

Spaces:
build-small-hackathon
/
dream-customs
Paused

App Files Community
56
dream-customs / docs /handoff.md
ADJCJH's picture
ADJCJH
Polish Dream QA final submission copy (#50)
d785bb1
preview code
|
Raw
History Blame Contribute Delete
7.53 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade

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:

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:

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.