dream-decoder 0.1.0

Dream journal analyzer with symbolic reasoning - hybrid Prolog rules + embeddings

Dream Decoder

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

# 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:

# 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

# 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

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

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=dream_decoder

License

MIT License