Hugging Face's logo

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

App Files Community
56
dream-customs / docs /handoff.md
ADJCJH's picture
ADJCJH
Prioritize Dream QA Today Tip card
81829c9 verified
preview code
|
Raw
History Blame
7.22 kB

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:

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 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?