README.md

metadata

title: Dream Customs
emoji: 🌤️
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 4.44.1
python_version: '3.10'
app_file: app.py
pinned: false
license: mit
short_description: Guided dream Q&A with one gentle today tip.
models:
  - openbmb/MiniCPM5-1B
  - openbmb/MiniCPM-V-4.6
tags:
  - gradio
  - minicpm
  - build-small-hackathon
  - dream-journal

Dream QA / 梦境问答台

A Build Small Hackathon Gradio app that helps users unpack a dream step by step and leave with one grounded tip for today.

The Hugging Face Space may still be named Dream Customs for continuity, but the current product direction is Dream QA: record a dream, answer or skip gentle follow-up questions, read a grounded interpretation draft, and receive a 今日小 Tips.

The public hackathon demo is English-first for international judges. A visible in-app language toggle keeps the Chinese experience available as 中文.

Concept

Dream QA accepts dream fragments by text, image, or voice. It turns those fragments into a shared dream intake, asks a grounded follow-up question, and returns a Today Tip card: one practical or caring suggestion first, an optional tiny action, and a short non-certain supporting reflection.

This is not a therapy, diagnosis, or prophecy product.

Models

• openbmb/MiniCPM-V-4.6 for image/sketch/note understanding.
• openbmb/MiniCPM5-1B for dream summary, follow-up questions, interpretation, and Today Tip 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.
• MiniCPM prompts are language-aware: English by default, Chinese when the user chooses 中文.

User Flow

1. Enter a dream by text, image, voice, or a mix.
2. State or let the app infer the main question.
3. Answer or skip one or more follow-up questions.
4. Receive one Today Tip tied to concrete dream details and the user's answer.
5. Read the supporting reflection if the user wants more context.

Language

• Default public UI: English.
• Toggle: English / 中文.
• English mode translates or paraphrases non-English dream anchors into natural English, so an international judge does not see mixed UI/model language.
• Chinese mode keeps the warm 梦境问答台 wording.
• Today Tips should be small and optional: "write the first sentence" beats "handle it immediately."

Current Direction References

• Product spec: docs/spec.md
• PRD: docs/prd.md
• Handoff: docs/handoff.md
• Design system: DESIGN.md
• Prototype images:
  • 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

Run

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

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.

Optional Hosted MiniCPM Routes

The public Space stays lightweight and can call private Modal endpoints through runtime secrets:

• DREAM_CUSTOMS_TEXT_ENDPOINT: Modal text route for openbmb/MiniCPM5-1B.
• DREAM_CUSTOMS_VISION_ENDPOINT: Modal vision route for openbmb/MiniCPM-V-4.6.
• DREAM_CUSTOMS_HOSTED_TOKEN: shared bearer token checked by Modal and sent by the Space.

Set these only as Hugging Face Space repository secrets or local shell variables. Do not store values in .env, docs, logs, screenshots, or git. Missing endpoints or route failures fall back to deterministic demo behavior.

The Gradio UI defaults to model for both text and vision backends, so a configured Space calls Modal by default. The demo backend remains available in developer settings as the deterministic fallback path.

The Hugging Face Space may run on ZeroGPU for hackathon hardware eligibility. dream_customs.zerogpu registers a lightweight @spaces.GPU startup probe so ZeroGPU accepts the app, but real MiniCPM inference still happens on the private Modal backend.

Token-safe text smoke:

python - <<'PY'
import os
from dream_customs.models import HostedMiniCPMTextClient

client = HostedMiniCPMTextClient(
    endpoint=os.environ["DREAM_CUSTOMS_TEXT_ENDPOINT"],
    token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
)
result = client.generate_negotiation("I missed an elevator in a foggy dream.")
print(result)
PY

Token-safe vision smoke:

python - <<'PY'
import os
from dream_customs.models import HostedMiniCPMVisionClient

client = HostedMiniCPMVisionClient(
    endpoint=os.environ["DREAM_CUSTOMS_VISION_ENDPOINT"],
    token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
)
print(client.extract_clues(os.environ["DREAM_CUSTOMS_SMOKE_IMAGE"]))
PY

Test

python -m pytest -q
python scripts/evaluate_today_tip_quality.py

Deployment Smoke Status

Latest local Dream QA refactor smoke:

• docs/smoke/2026-06-08-dream-qa-refactor-smoke.md
• docs/smoke/2026-06-08-post-refactor-polish-smoke.md

Historical smoke notes under docs/smoke/ describe earlier pact/customs UI passes. They remain useful deployment history, but the current implementation target is the Dream QA flow documented in docs/handoff.md, docs/spec.md, and docs/prd.md.

Safety

This is not a therapy or diagnosis product. It gives playful reflection, one small today tip, and escalation copy for severe distress.