dream-decoder 0.1.0
Dream journal analyzer with symbolic reasoning - hybrid Prolog rules + embeddings
License: MIT
Requires Python: >=3.9
Keywords: dreams, journal, prolog, embeddings, symbolic-ai, nlp

# Dream Decoder

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/brody4321)

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/brody4321)

A dream journal analyzer that combines **Prolog-based symbolic reasoning** with **neural embeddings** for dream interpretation and pattern analysis.

## Features

- **Symbol Extraction**: Automatically detects dream symbols using both keyword matching and semantic embeddings (sentence-transformers)
- **Symbolic Reasoning**: Prolog rules for psychological interpretation of dream symbols, with Python fallback
- **Pattern Analysis**: Tracks recurring themes, symbol associations, and temporal patterns
- **Visualization**: Generate charts for symbol frequencies, theme timelines, and association networks
- **CLI Interface**: Full command-line interface for managing your dream journal

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/dream-decoder.git
cd dream-decoder

# Install with pip
pip install -e .
```

### Optional: SWI-Prolog

For full symbolic reasoning capabilities, install SWI-Prolog:

```bash
# Ubuntu/Debian
sudo apt-get install swi-prolog

# macOS
brew install swi-prolog

# Windows
# Download from https://www.swi-prolog.org/download/stable
```

If SWI-Prolog is not available, the system automatically falls back to Python-based reasoning.

## Quick Start

### CLI Usage

```bash
# Add a new dream
dream-decoder add --title "Flying Dream" --mood peaceful --lucidity 7

# View recent dreams
dream-decoder list

# View a specific dream
dream-decoder view 1

# Search dreams
dream-decoder search "ocean"

# Find dreams with a symbol
dream-decoder symbol water

# Get journal statistics
dream-decoder stats

# Analyze patterns
dream-decoder patterns

# Generate visualizations
dream-decoder visualize --output ./charts

# Export journal
dream-decoder export --format markdown --output dreams.md
```

### Library Usage

```python
from dream_decoder import DreamJournal

# Create a journal
journal = DreamJournal(db_path="my_dreams.db")

# Add a dream
entry = journal.add_dream(
    content="I was flying over a vast ocean when suddenly I started falling...",
    title="Flying and Falling",
    mood="anxious",
    lucidity=5,
)

# View analysis results
print(f"Symbols: {entry.symbols}")
print(f"Themes: {entry.themes}")
print(f"Interpretations: {entry.interpretations}")

# Find similar dreams
similar = journal.find_similar_dreams(entry, limit=5)

# Get recurring patterns
patterns = journal.pattern_analyzer.detect_recurring_patterns()

# Predict likely themes for future dreams
predictions = journal.predict_themes()
```

## Architecture

```
dream_decoder/
├── storage.py      # SQLite database layer with DreamEntry model
├── journal.py      # Main interface coordinating all components
├── symbols.py      # Embedding-based symbol extraction
├── reasoning.py    # Prolog interface with Python fallback
├── patterns.py     # Pattern detection and statistical analysis
├── visualization.py # Matplotlib/NetworkX visualizations
├── cli.py          # Click-based CLI
└── rules/
    └── symbols.pl  # Prolog knowledge base
```

### Hybrid AI Approach

1. **Symbol Extraction**: Uses `sentence-transformers` (all-MiniLM-L6-v2) to compute embeddings and find semantically similar symbols
2. **Symbolic Reasoning**: Prolog rules define relationships between symbols, emotions, and themes
3. **Pattern Analysis**: Statistical analysis of symbol co-occurrences and temporal patterns
4. **Clustering**: K-means clustering on dream embeddings to find related dreams

## Dream Symbols

The system recognizes 60+ common dream symbols across categories:

| Category | Examples |
|----------|----------|
| Nature | water, ocean, forest, mountain, fire, storm |
| Places | house, school, bridge, door, stairs, basement |
| People | mother, father, stranger, shadow_figure |
| Animals | snake, spider, bird, wolf, butterfly |
| Actions | flying, falling, running, being_chased, drowning |
| Objects | key, mirror, clock, money, car |

### Detected Themes

- **Transformation**: snake, butterfly, death, fire
- **Anxiety**: falling, being_chased, teeth_falling, naked
- **Spiritual Journey**: stairs, mountain, flying, bird
- **Relationships**: mother, father, friend, stranger
- **Shadow Work**: shadow_figure, monster, basement
- **Freedom Seeking**: flying, bird, ocean, running
- **Emotional Processing**: water, ocean, rain, drowning

## CLI Commands

| Command | Description |
|---------|-------------|
| `add` | Add a new dream entry |
| `view <id>` | View a specific dream |
| `list` | List recent dreams |
| `search <query>` | Search dream content |
| `symbol <name>` | Find dreams with a symbol |
| `similar <id>` | Find similar dreams |
| `analyze <id>` | Re-analyze a dream |
| `delete <id>` | Delete a dream |
| `stats` | Show journal statistics |
| `patterns` | Analyze recurring patterns |
| `interpret <symbol>` | Get symbol interpretations |
| `visualize` | Generate visualization charts |
| `export` | Export journal to JSON/Markdown |

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=dream_decoder
```

## License

MIT License