Skip to content

kaiyes/dreamcatcher

BranchesTags

Repository files navigation

DreamCatcher - Islamic Dream Interpreter

Fully offline AI-powered dream interpretation app based on Ibn Sirin's teachings with local LLM, voice input, and no server dependencies

📋 Table of Contents

🎯 Project Overview

DreamCatcher is a fully offline React Native app that interprets dreams using:

  • Ibn Sirin's Dictionary of Dreams: 2,157 unique dream symbols (bundled)
  • Local AI: Runs offline with Llama-based models (Qwen2.5, SmolLlama, LFM2.5)
  • RAG (Retrieval-Augmented Generation): Keyword-based symbol matching with LLM interpretation
  • Voice Input: Whisper STT for hands-free dream recording
  • Persistent Storage: AsyncStorage for chat history

Primary Use Case: Islamic dream interpretation with traditional symbol meanings enhanced by AI analysis

🏗️ Architecture

┌──────────────────────────────────────────────────────┐
│          React Native App (Fully Offline)          │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐                  │
│  │  Screens    │  │  Services   │                  │
│  │ - Dream     │  │ - localLLM  │                  │
│  │ - History   │  │ - whisper   │                  │
│  │ - Symbols   │  │ - rag       │                  │
│  └─────────────┘  │ - symbols   │                  │
│                   │ - chat      │                  │
│                   └─────────────┘                  │
│                                                      │
│  ┌────────────────────────────────────────────┐   │
│  │         Local Storage (AsyncStorage)        │   │
│  │  - Chat history                             │   │
│  │  - Model preferences                        │   │
│  └────────────────────────────────────────────┘   │
│                                                      │
│  ┌────────────────────────────────────────────┐   │
│  │       Bundled Data & Downloaded Models     │   │
│  │  - Ibn Sirin's Dictionary (JSON)           │   │
│  │  - Whisper model (ggml-base.bin)           │   │
│  │  - Local LLM models (downloaded at runtime)│   │
│  └────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

✨ Features

Current Features

1. Dream Interpretation

  • Symbol-based lookup: Keyword matching through 2,157 dream symbols
  • AI-powered analysis: Local LLM provides contextual interpretation
  • RAG Integration: Combines symbol meanings with LLM reasoning
  • Chat Interface: Persistent dream history with timestamps

2. Voice Input

  • Speech-to-Text: Whisper model for hands-free dream recording
  • Auto-transcription: Immediate conversion to text

3. Fully Offline

  • No servers needed: Everything runs locally on-device
  • No internet required: Works completely offline
  • Model management: Download optional AI models for better interpretations

4. Symbol Encyclopedia

  • Full symbol catalog: Browse all 2,157 Ibn Sirin symbols
  • Search functionality: Quick symbol lookup with related terms
  • Detailed interpretations: Complete symbol meanings

5. Chat History

  • Persistent storage: All dreams saved locally
  • Swipeable management: Delete individual chats or clear all
  • Full conversations: Review complete dream interpretation threads

🚀 Quick Start

Prerequisites

  • Node.js: >= 20
  • Ruby & Bundler: For CocoaPods (iOS)
  • Xcode: For iOS development (macOS only)
  • Android Studio: For Android development (optional)

Installation

# Clone repository
git clone https://github.com/kaiyes/dreamcatcher.git
cd dreamCatcher

# Install dependencies
npm install

# iOS: Install CocoaPods
cd ios && bundle exec pod install && cd ..

Run the App

# Terminal 1: Start the app (iOS)
npm run ios

# OR Android
npm run android

That's it! No servers or additional setup needed.

🛠️ Development Setup

Project Structure

dreamCatcher/
├── src/
│   ├── screens/
│   │   ├── dreamInterpret.screen.js    # Main chat UI
│   │   ├── chatHistory.screen.js       # View saved chats
│   │   ├── chatDetail.screen.js        # Full conversation
│   │   ├── symbolList.screen.js        # Browse symbols
│   │   ├── symbolDetail.screen.js      # Symbol details
│   │   └── localLLMTest.screen.js      # Model management
│   ├── services/
│   │   ├── localLLM.service.js         # Local AI models
│   │   ├── whisper.service.js          # Voice input
│   │   ├── rag.service.js              # Symbol retrieval
│   │   ├── symbols.service.js          # Symbol search
│   │   └── chat.service.js             # Chat persistence
│   ├── util/
│   │   ├── symbols_full.json           # Ibn Sirin's Dictionary
│   │   ├── symbolEmbeddings.json       # Search index
│   │   └── prompt.js                   # LLM prompts
│   ├── assets/                         # Images & icons
│   └── Navigation.js                   # Route configuration
├── ios/
│   └── Podfile                         # Native dependencies
├── android/
│   └── build.gradle                    # Android config
├── metro.config.js                     # Bundler config
└── package.json                        # Dependencies

Key Files

metro.config.js: Configured to bundle model files

  • .bin (Whisper model)
  • .json (Embedding index, symbol database)
  • .onnx (Model formats)

.gitignore: Excludes downloaded models (they're stored locally on-device)

🔌 Services

1. Local LLM Service (localLLM.service.js)

Purpose: Download and run AI models locally

Available Models:

Model Size Speed Quality
SmolLlama 101M (Q3_K_M) 44MB Fast Good
Qwen2.5 1.5B (Q4_0) 934MB Medium Excellent
LFM2.5 1.2B (Q4_0) 790MB Medium Excellent

Functions:

  • downloadModel(modelKey, onProgress) - Download from Hugging Face
  • initLocalLLM(modelKey) - Load model for inference
  • completeLocalLLM(prompt) - Generate dream interpretation

Model Context: 2048 tokens, GPU acceleration available

2. Whisper Service (whisper.service.js)

Purpose: Speech-to-text for dream recording

Model: ggml-base.bin (bundled in app)

Functions:

  • initWhisperModel() - Load model
  • startRecording() - Begin audio capture
  • stopAndTranscribe() - Stop and transcribe
  • cancelRecording() - Cancel without transcription

Audio Config:

{
  sampleRate: 16000,
  channels: 1,
  bitsPerSample: 16,
  format: 'wav'
}

3. RAG Service (rag.service.js)

Purpose: Retrieve relevant dream symbols for interpretation

Search Strategy: Keyword matching with relevance scoring

  • Multi-level matching (exact, prefix, substring)
  • Stop word filtering
  • Ranked results by relevance

Functions:

  • findMatchingSymbols(dreamText) - Find symbols in dream description
  • Returns sorted list with names, meanings, related terms

Fallback: Displays raw Ibn Sirin definitions if LLM not available

4. Symbols Service (symbols.service.js)

Purpose: Direct symbol lookup and search

Functions:

  • searchSymbols(query) - Find symbols by name/keywords
  • getSymbolById(id) - Get specific symbol
  • getAllSymbols() - Get full dictionary
  • extractKeywords(dreamText) - Parse dream for keywords

5. Chat Service (chat.service.js)

Purpose: Persistent chat history

Functions:

  • getChats() - Get all saved chats
  • getChat(id) - Get specific chat
  • saveChat(chat) - Save new chat
  • deleteChat(id) - Delete individual chat
  • deleteAllChats() - Clear all history
  • addMessageToChat(id, message) - Add message to existing chat

Storage: AsyncStorage (local device storage)

📱 Screens

1. Dream Interpret Screen

Purpose: Main interface for dream interpretation

Features:

  • Text input with send button
  • Voice recording button (Whisper)
  • Real-time streaming LLM responses
  • Symbol list display
  • Model selector modal
  • "New Chat" and "Chat History" buttons
  • Examples on empty state

Flow:

  1. User describes dream (text or voice)
  2. RAG finds matching symbols
  3. LLM (if loaded) combines with symbol meanings
  4. Results displayed with formatting
  5. Saved to chat history

2. Chat History Screen

Purpose: Browse all saved dreams

Features:

  • List of all chats with timestamps
  • Last message preview
  • Message count badge
  • Swipe to delete individual chats
  • "Delete All" button
  • Tap to view full conversation

3. Chat Detail Screen

Purpose: View full dream interpretation

Features:

  • Dream description header
  • Message thread with timestamps
  • User messages (right-aligned, blue)
  • AI responses (left-aligned, white)
  • Formatted text with bold support
  • Delete chat button

4. Symbol List Screen

Purpose: Browse all dream symbols

Features:

  • Searchable encyclopedia
  • Autocomplete filtering
  • Shows related terms as tags
  • Tap to view details
  • Sorted alphabetically
  • Result counter

5. Symbol Detail Screen

Purpose: View complete symbol interpretation

Features:

  • Full Ibn Sirin interpretation
  • "See Also" related symbols
  • Clickable navigation to related symbols

6. Local LLM Test Screen

Purpose: Model management and configuration

Features:

  • Download available models
  • Progress tracking with visual bar
  • Initialize/activate models
  • Shows active model badge
  • Model info (name, size, status)
  • Resumable downloads
  • Error handling and status messages

📦 Local Models

Model Types

Model Location Purpose
Whisper (ggml-base.bin) Bundled Speech-to-text
Qwen2.5 / SmolLlama / LFM2.5 Downloaded Dream interpretation
Symbol Embeddings Bundled Search index
Ibn Sirin Dictionary Bundled Symbol database

Why Local Models?

  • Privacy: No data leaves device
  • Speed: No network latency
  • Offline: Works without internet
  • Control: Choose which models to download

First Time Setup

When you first open the app:

  1. Voice input works immediately (Whisper bundled)
  2. Symbol search works immediately (dictionary bundled)
  3. AI interpretation requires downloading a model (~44MB - 934MB)
  4. Tap "Manage Models" on dream screen to download

🐛 Troubleshooting

Voice Input Not Working

Problem: Whisper initialization fails

  • Solutions:
    • Grant microphone permission (check iOS Settings)
    • Ensure ggml-base.bin was bundled correctly
    • Check Metro config for .bin extension

LLM Download Fails

Problem: Model download interrupted or stuck

  • Solutions:
    • Check internet connection
    • Downloads are resumable - retry will continue
    • Try smaller model (SmolLlama 44MB) first
    • Check device has enough storage space

Build Issues

Problem: iOS build fails

  • Solutions: 
    # Clean and rebuild
cd ios
rm -rf Pods Podfile.lock
bundle exec pod install
cd ..
npm run ios

Problem: Metro bundler errors

  • Solutions: 
    # Clear cache and restart
npx react-native start --reset-cache

App Crashes on LLM Inference

Problem: LLM generation causes crash

  • Solutions:
    • Try smaller model (44MB SmolLlama)
    • Ensure sufficient device RAM
    • Restart app before inference

🚀 Future Plans

Phase 1: Current (Complete)

  • Dream interpretation with local LLM
  • Symbol database integration
  • Voice input (Whisper)
  • Chat history persistence
  • Offline functionality
  • RAG-based symbol retrieval

Phase 2: Enhancements

  • Streaming LLM responses (faster display)
  • Symbol relationship visualization
  • Dream journal analytics
  • Advanced search filters

Phase 3: Advanced AI

  • Multiple language support (Urdu, Arabic)
  • Fine-tuned dream interpretation models
  • Cloud backup (optional)
  • User authentication

Phase 4: Production

  • Performance optimization
  • App Store submission
  • Play Store submission
  • Analytics and crash reporting

📝 Data Sources

Ibn Sirin's Dictionary of Dreams

Source: Islamic dream interpretation classical text

Symbol Count: 2,157 unique symbols

Structure:

{
  "tree": {
    "name": "Tree",
    "interpretation": "A tree in a dream represents a man...",
    "related": ["Garden", "Fruit", "Shade"],
    "see_also": ["Plant", "Forest"]
  }
}

Indexing: O(1) keyword lookup for fast symbol matching

📄 License

[Add your license here]

👥 Contributing

[Add contribution guidelines here]

📞 Support

For issues or questions:

  • Open an issue on GitHub
  • Contact: [Your contact info]

🙏 Acknowledgments

  • Ibn Sirin's Dictionary of Dreams (8th century Islamic scholar)
  • Whisper.ai (OpenAI Speech-to-Text)
  • Ollama & Llama models
  • React Native community

Last Updated: January 28, 2026 Version: 0.0.1 (Development) Status: Fully Offline & Local - No Server Dependencies

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages