# Dream Customs / 梦境海关 PRD

Last updated: 2026-06-05

## 1. Executive Summary

### Problem Statement

Users who wake up from frequent or vivid dreams may feel unsettled, tired, or mentally cluttered. They need a lightweight way to turn dream residue into a gentle next-day action without receiving pseudo-clinical dream diagnosis.

### Proposed Solution

Dream Customs is a Gradio app that accepts voice, image, and text dream declarations, normalizes them into a structured dream intake, and uses MiniCPM models to generate a playful "dream alliance" card with practical advice, a weird 5-minute task, and a bedtime release phrase.

### Success Criteria

- A user can complete the core flow from input to final card in <= 90 seconds on the hosted demo.
- At least 90% of demo runs produce a parseable final output object matching the required schema.
- At least 5 real users can understand the output without extra explanation and rate it >= 4/5 for delight.
- At least 3 real users report that the "today's pact" feels actionable.
- The app runs with total model parameters <= 32B and is packaged for Gradio/Hugging Face Space.

## 2. User Experience & Functionality

### User Personas

1. Primary persona: vivid dreamer.
   - Recently sleeps poorly or wakes with strong dream fragments.
   - Wants a small morning ritual, not therapy.

2. Secondary persona: playful AI explorer.
   - Wants a strange AI experience worth showing a friend.
   - Cares about creativity and shareable outputs.

3. Demo viewer / judge.
   - Needs to understand the interaction in under one minute.
   - Looks for clear small-model fit and Gradio polish.

### User Stories

#### Story 1: Text Dream Declaration

As a vivid dreamer, I want to type my dream so that I can get a next-day pact even if I have no image or audio.

Acceptance criteria:

- User can submit text-only input.
- App creates a valid `DreamIntake` object.
- Final card includes dream visitor, practical suggestion, weird task, and bedtime release phrase.

#### Story 2: Image Dream Declaration

As a user who remembers images better than words, I want to upload a sketch or bedside note so that the system can use visual dream clues.

Acceptance criteria:

- User can upload one image.
- MiniCPM-V-4.6 extracts at least 3 visual clues when visible content exists.
- Visual clues are included in the final `DreamIntake`.
- If image extraction fails, text-only flow still works.

#### Story 3: Voice Dream Declaration

As a half-awake user, I want to speak my dream so that I do not need to type immediately after waking.

Acceptance criteria:

- User can record or upload an audio clip.
- ASR adapter returns a transcript.
- Transcript is visible/editable before final submission or transparently included in the declaration.
- If ASR fails, user receives a concise fallback message and can type manually.

#### Story 4: Alliance Negotiation

As a user, I want the AI to ask me a few questions so that the final advice feels connected to my dream.

Acceptance criteria:

- App generates 2-3 questions.
- User can answer all, answer some, or skip.
- Skip path still generates a final card.

#### Story 5: Today's Pact Card

As a user, I want a visually clear output card so that I can screenshot or share the result.

Acceptance criteria:

- Card includes all required output fields.
- Card is readable on mobile and desktop.
- Card avoids medical or diagnostic framing.
- Card includes a short safety note only when needed.

### Non-Goals

- Medical diagnosis or therapy.
- Sleep-stage tracking.
- Long-term journaling database.
- Account creation.
- Voice output in MVP.
- Social feed or leaderboard.
- Fine-tuning during the hackathon MVP.

## 3. AI System Requirements

### Tool Requirements

- MiniCPM-V-4.6 for image-to-text visual clue extraction.
- MiniCPM5-1B for text reasoning, persona, structured output, and alliance card generation.
- A small ASR adapter for voice-to-text. This adapter is not the core AI experience.
- Gradio for UI.
- Optional HTML/CSS card renderer.

### Prompt Requirements

Prompts must:

- Ask for JSON-compatible output.
- Keep the tone playful, gentle, and non-clinical.
- Avoid strong claims about dream meaning.
- Include a safety boundary for severe distress.
- Keep final advice small enough to execute in 5-10 minutes.

### Evaluation Strategy

Create an eval set with at least 12 dream inputs:

- 4 text-only dreams.
- 3 image-assisted dreams.
- 3 voice-transcript dreams.
- 2 distress-edge cases.

Measure:

- Schema validity.
- Tone safety.
- Practicality of advice.
- Weird-task delight.
- Ability to recover from missing modality.

Pass thresholds:

- Schema validity: >= 90%.
- No diagnostic language in ordinary cases: 100%.
- Safety note appears in distress-edge cases: >= 90%.
- Human delight rating on 5 demo cases: average >= 4/5.

## 4. Technical Specifications

### Architecture Overview

```text
Gradio inputs
  -> text input
  -> image upload -> MiniCPM-V-4.6 visual clue extractor
  -> audio upload/record -> ASR adapter
  -> DreamIntake builder
  -> MiniCPM5-1B customs officer prompt
  -> negotiation questions
  -> final MiniCPM5-1B pact prompt
  -> HTML card renderer
```

### Core Components

- `app.py`: Gradio UI composition and event wiring.
- `dream_customs/schema.py`: dataclasses or Pydantic models for inputs and outputs.
- `dream_customs/models.py`: model/client loading and inference wrappers.
- `dream_customs/prompts.py`: prompt templates.
- `dream_customs/pipeline.py`: orchestration logic.
- `dream_customs/safety.py`: lightweight safety checks and copy.
- `dream_customs/render.py`: HTML card rendering.
- `tests/`: schema, prompt, safety, and pipeline unit tests with mocked model outputs.

### Integration Points

- Hugging Face Space runtime.
- Hugging Face model downloads or inference endpoints.
- Gradio audio, image, and text components.
- Optional model cache in Space environment.

### Security & Privacy

- Do not persist user dreams by default.
- Do not log raw dream text or uploaded images in production demo logs.
- Provide visible copy: "This is a playful reflection tool, not medical advice."
- Do not require account login.

## 5. Risks & Roadmap

### Phased Rollout

#### MVP

- Text, image, and voice input.
- Dream intake normalization.
- MiniCPM-V-4.6 image clue extraction.
- MiniCPM5-1B negotiation and final card.
- HTML output card.
- Safety boundary.

#### v1.1

- More polished card export.
- Better example gallery.
- Optional bilingual output.
- More robust eval harness.

#### v2.0

- Voice output through VoxCPM2.
- Local dream history stored only in browser/session.
- Multiple customs officer styles.

### Technical Risks

- MiniCPM-V-4.6 may be heavy for Space hardware if loaded locally.
- MiniCPM5-1B output may fail strict JSON without repair.
- ASR adapter may complicate dependencies.
- Audio input on mobile browsers may behave inconsistently.
- Safety classification may be too weak if only prompt-based.

### Mitigations

- Keep text-only demo path always functional.
- Add JSON repair and schema validation.
- Use examples with fixed sample media for demo recording.
- Make ASR optional and fallback to manual transcript.
- Keep image extraction output concise to reduce latency.