QUICKSTART.md

# 🚀 Quick Start Guide

Get DReamMachine running in 5 minutes!

## Step 1: Install Dependencies

```bash
pip install -r requirements.txt
```

## Step 2: Set Up HuggingFace Token

Get your token from: https://huggingface.co/settings/tokens

**Option A: Environment Variable**
```bash
export HF_TOKEN=your_token_here
```

**Option B: .env File**
```bash
cp .env.example .env
# Edit .env and add your token
```

## Step 3: Verify Setup

```bash
python setup.py
```

You should see all checks pass ✓

## Step 4: Run Your First Dream!

### Option A: Gradio Web Interface (Recommended)

```bash
python app.py
```

Then open: http://localhost:7860

1. Go to "Single Dream Round" tab
2. Keep the default stage "init_1_25"
3. Click "🚀 Run Dream Round"
4. Wait 2-5 minutes
5. Review the amazing results!

### Option B: Command Line

```bash
python run_cli.py --single
```

## What Happens During a Dream Round?

```
[A.1] Setup → Load prompts and constraints
[A.2] Dream → 3 LLMs generate creative ideas
[A.3] Refine → Writer/Logger/Narrator create narrative
[A.4] Analyze → Deep Thinker evaluates feasibility
[A.5] Score → Curator assigns final grades
[A.6] Log → Save to local files + HF Dataset
[A.7] Decide → Advance idea or start new one?
```

Takes 2-5 minutes depending on API response times.

## Understanding Your Results

### Session Summary

```
Originality: 9/10       ← How novel is it?
Feasibility: 8/10       ← Can it be built?
Global Impact: 9/10     ← How many people benefit?
Narrative Coherence: 8/10 ← Is the story good?

Reforge Flag: ✓ Yes    ← Advances to next stage!
```

**Reforge Flag = True** means the idea was good enough to advance!

### The Outputs

1. **Narrative Pitch** - Compelling story about the invention
2. **Technical Components** - What's needed to build it
3. **Feasibility Report** - Scientific evaluation
4. **Curator Scorecard** - Detailed scoring breakdown

## Try Different Stages

Once you've run `init_1_25` successfully:

```bash
# Try mid-life crisis stage
python run_cli.py --single --stage mid_26_50

# Try late-life adoption stage
python run_cli.py --single --stage late_51_75

# Try final legacy stage
python run_cli.py --single --stage final_76_100
```

## Run Multiple Dreams (Batch Mode)

### Via Web Interface

1. Go to "Batch Mode" tab
2. Set rounds: 5
3. Set interval: 30 seconds
4. Click "Run Batch Mode"
5. Get coffee ☕ (takes ~15 minutes)

### Via CLI

```bash
# Run 5 rounds with 30-second intervals
python run_cli.py --batch 5 --interval 30
```

## View Your Session History

### Web Interface

1. Go to "Session History" tab
2. Click "🔄 Refresh History"
3. Browse all your past dreams!

### File System

Check the `logs/` directory:
```bash
ls logs/
# session_20250114_123045_0.json
# session_20250114_124512_1.json
# ...
```

## Customize Configuration

Edit `config.yaml` to change:

- **Models**: Use different LLMs
- **Constraints**: Change what ideas must satisfy
- **Thresholds**: Adjust scoring requirements
- **Prompts**: Modify detail level

## Common Issues

**"HF_TOKEN not found"**
→ Set the environment variable or add to .env file

**"Rate limit exceeded"**
→ Add more sleep time between rounds
→ Use `--interval 60` for batch mode

**"Model timeout"**
→ Normal for large models, will retry automatically
→ Consider using smaller/faster models for testing

## Next Steps

- Read the full [README.md](README.md) for advanced features
- Customize prompts in `prompt_manager.py`
- Deploy to HuggingFace Spaces for 24/7 dreaming
- Share your best discoveries!

---

**Happy Dreaming! 🌟**