upload from github

.env.example

@@ -0,0 +1,22 @@
+# Neo4j Aura Database Configuration
+# Get these values from your Neo4j Aura instance
+# Visit: https://console.neo4j.io/
+
+# Neo4j Connection String
+# Format: neo4j+ssc://xxxxxxxx.databases.neo4j.io or neo4j://hostname:port
+NEO4J_URI=neo4j+ssc://your-instance-id.databases.neo4j.io
+
+# Neo4j Username (usually 'neo4j')
+NEO4J_USER=neo4j
+
+# Neo4j Password (from Aura instance creation)
+NEO4J_PASSWORD=your-secure-password-here
+
+# Google Gemini API Configuration
+# Get your free API key from: https://aistudio.google.com/app/apikey
+GOOGLE_API_KEY=your_google_api_key_here
+
+# Optional: Tavily Web Search API
+# Get your API key from: https://app.tavily.com
+# Leave empty to use mock data for Search Agent
+TAVILY_API_KEY=your_tavily_api_key_here

.gitignore

@@ -0,0 +1,217 @@
+.github/
+.vscode/
+
+# .DS_Store
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+
+# Ignore database files
+*.db
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+/bdenv
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kshitij Nevrekar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,20 +1,675 @@
+# 🧠 Brain Dump Sanctuary
+
+> **Capture, cluster, and reflect on your thoughts in real-time.**
+
+A full-stack NLP application that transforms scattered thoughts into organized, semantically meaningful clusters with AI-powered insights. Built with Streamlit, LangGraph agents, and Neo4j.
+
+---
+
+## ✨ Features
+
+### Core Capabilities
+- **💭 Brain Dump Capture**: Write down thoughts, ideas, and questions instantly
+- **🔗 Semantic Clustering**: Automatically group related thoughts using embeddings (sentence-transformers) and HDBSCAN
+- **📊 Interactive Knowledge Graph**: Visualize all thoughts as an interactive Plotly graph with color-coded clusters
+- **🏷️ AI-Generated Labels**: Auto-label clusters using Google Gemini LLM (e.g., "Personal Growth", "Technical Concepts")
+- **🤖 Multi-Agent Intelligence**:
+  - **SearchAgent**: Generate contextualized summaries with optional web search (Tavily)
+  - **QuestionAgent**: Generate Socratic questions for deeper reflection
+  - **GenerationAgent**: Synthesize insights across related thoughts
+  - **FeedAgent**: Curate a blog-style feed of your 5 most recent thoughts with agent insights
+- **📝 Persistent Storage**: All thoughts stored in Neo4j graph database with full history
+- **🔄 Real-time Updates**: Refresh embeddings and recalculate clusters on demand
+
+### Two-View Interface
+1. **Home Tab** 🏠: Semantic cluster map + comprehensive table of all thoughts
+2. **Feed Tab** 📰: Blog-style cards with summaries and reflection questions
+
+---
+
+## 🏗️ Architecture
+
+### Tech Stack
+```
+Frontend:          Streamlit (single-page Python web app)
+Backend:           Python 3.10+ with LangChain/LangGraph
+Database:          Neo4j Aura (graph database)
+NLP Pipeline:      
+  - Embeddings:    sentence-transformers (all-MiniLM-L6-v2)
+  - Clustering:    HDBSCAN + UMAP dimensionality reduction
+  - LLM:           Google Gemini 2.5 Flash (via LangChain)
+Search:            Tavily API (optional, with mock fallback)
+```
+
+### System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    STREAMLIT UI                         │
+│  (app.py - Home Tab | Feed Tab | Sidebar Controls)     │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+        ┌─────────┴─────────┐
+        │                   │
+    ┌───▼────┐         ┌────▼──────┐
+    │ AGENTS │         │ EMBEDDINGS │
+    │ (Day2) │         │ & CLUSTERS │
+    └───┬────┘         │ (Day 1)    │
+        │              └────┬───────┘
+        │                   │
+    ┌───┴───────────────────▼────┐
+    │    BRAINDUMP_CORE.PY       │
+    │  - BrainDumpDB (Neo4j)     │
+    │  - EmbeddingEngine         │
+    │  - ClusterEngine           │
+    │  - ClusterLabelEngine      │
+    └───┬────────────────────────┘
+        │
+    ┌───▼──────────────────┐
+    │   NEO4J GRAPH DB     │
+    │  (Aura Cloud)        │
+    │  - Dump Nodes        │
+    │  - Cluster Nodes     │
+    │  - Relationships     │
+    └──────────────────────┘
+```
+
+### Data Flow
+
+**Input → Processing → Storage → Visualization**
+
+1. **User enters brain dump** → `app.py` sidebar
+2. **Generate embedding** → `EmbeddingEngine` (sentence-transformer)
+3. **Store in Neo4j** → `BrainDumpDB.add_dump()`
+4. **Re-cluster on demand** → `ClusterEngine.cluster()` + `ClusterLabelEngine.label_clusters()`
+5. **Visualize clusters** → Plotly interactive graph (Home tab)
+6. **Enrich with AI** → Agents analyze for Feed tab
+
+### Neo4j Graph Schema
+
+```cypher
+Node: Dump
+├── id: UUID
+├── text: String (the brain dump)
+├── embedding: Vector[384] (from sentence-transformer)
+├── created_at: DateTime
+└── cluster_id: Reference to Cluster
+
+Node: Cluster
+├── id: UUID
+├── label: String (e.g., "Personal Growth")
+├── description: String (optional)
+├── created_at: DateTime
+
+Relationships:
+├── Dump -[:IN_CLUSTER]-> Cluster
+└── Dump -[:SIMILAR_TO {weight: 0.0-1.0}]-> Dump
+```
+
+### Component Breakdown
+
+| File | Purpose | Key Classes |
+|------|---------|------------|
+| `app.py` | Streamlit UI & session management | Main app logic, page layout |
+| `braindump_core.py` | NLP pipeline & database | `BrainDumpDB`, `EmbeddingEngine`, `ClusterEngine`, `ClusterLabelEngine` |
+| `agents.py` | AI agents for insights | `QuestionAgent`, `SearchAgent`, `GenerationAgent`, `FeedAgent` |
+| `neo4j_maintenance.py` | Database utilities | Neo4j query helpers, debugging |
+| `cleanup_db.py` | Reset database | Wipe all data (for testing) |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+
+- Neo4j Aura account (free tier available)
+- API keys for Google Gemini (free) and optionally Tavily
+
+### 1. Setup Neo4j (Required)
+
+Create a free Neo4j Aura instance:
+1. Go to https://console.neo4j.io/
+2. Sign up for a free account
+3. Create a new "Free" Aura instance
+4. Copy your connection details:
+   - **URI**: `neo4j+ssc://xxxxx.databases.neo4j.io`
+   - **Username**: `neo4j`
+   - **Password**: (set during creation)
+
+### 2. Installation
+
+```bash
+# Clone repository
+git clone <repo-url>
+cd braindump-sanctuary
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Create environment file
+cp .env.example .env  # or create manually
+
+# Edit .env with your credentials
+```
+
+**.env Template:**
+```env
+# Neo4j (Required)
+NEO4J_URI=neo4j+ssc://your-instance-id.databases.neo4j.io
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your-password-here
+
+# Google Gemini (Required for AI features)
+GOOGLE_API_KEY=your_google_api_key_here
+
+# Web Search (Optional - uses mock data if not provided)
+TAVILY_API_KEY=your_tavily_api_key_here
+
+# Alternative: Perplexity (Optional)
+PERPLEXITY_API_KEY=your_perplexity_key_here
+```
+
+**Get API Keys:**
+- 🔑 **Google Gemini** (free): https://aistudio.google.com/app/apikey
+- 🔍 **Tavily Search** (optional): https://app.tavily.com
+- 🧠 **Perplexity** (optional): https://www.perplexity.ai/
+
+### 3. Run the App
+
+```bash
+streamlit run app.py
+```
+
+App opens at `http://localhost:8501`
+
+---
+
+## 📱 User Interface Guide
+
+### Sidebar Controls
+
+**Left Sidebar** - Main interaction hub:
+- 🗺️ **Navigation**: Radio buttons to toggle between **Home** and **Feed** tabs
+- 📝 **Text Area**: Input field for new brain dumps
+- ✅ **Add to Sanctuary**: Save the thought to Neo4j
+- 🗑️ **Clear**: Empty the input field
+- 🔄 **Refresh Clusters**: Recalculate all embeddings and clusters (computationally intensive, 10-30 seconds)
+- ⚠️ **Clear All Dumps**: Permanently delete all thoughts from the database
+- 📊 **Total Brain Dumps**: Counter showing total stored thoughts
+
+### Home Tab 🏠 - Knowledge Graph View
+
+**Top Section: Interactive Cluster Map**
+- **Visualization**: 2D interactive Plotly graph
+- **Nodes**: Each point = one brain dump
+- **Colors**: Each color = a semantic cluster (similar ideas grouped together)
+- **Layout**: UMAP dimensionality reduction for spatial meaning
+- **Interactions**: Hover to see full text, zoom/pan to explore
+- **Relationships**: Edges show semantic similarity between thoughts
+
+**Bottom Section: Comprehensive Table**
+- **Columns**: Brain Dump | Cluster Label | Created At
+- **Sorting**: Most recent first (newest at top)
+- **Format**: Plain text, easy to copy
+
+**Actions**:
+- Click "🔄 **Refresh Clusters**" to recalculate (when you add many new thoughts)
+- Spinner animations show progress of embedding generation and labeling
+
+### Feed Tab 📰 - Blog-Style Feed
+
+**What You See**:
+1. **Up to 5 Recent Cards** in reverse chronological order
+2. **Each Card Contains**:
+   - 💭 **Title**: Your full brain dump text
+   - 🏷️ **Cluster Badge**: Category label (generated by LLM)
+   - 📄 **Summary**: AI-generated context
+     - If Tavily API set: Real web search + synthesis
+     - If not: Mock contextual data (demo mode)
+   - ❓ **Reflection Questions**: 5 Socratic questions (from QuestionAgent)
+
+**Why Use Feed?**
+- Quick morning review without table scrolling
+- AI-generated insights help you think deeper
+- Guided reflection via questions
+- Patterns become visible across multiple cards
+- Perfect for journaling workflow
+
+---
+
+## 🔄 Typical Workflows
+
+### Workflow 1: Daily Brain Dumping + Review
+```
+Morning:
+1. Open app at http://localhost:8501
+2. Sidebar: Type 3-5 quick thoughts
+3. Click "Add to Sanctuary" each time
+4. Switch to Feed tab
+5. Read summaries and reflect on questions
+6. (Takes 5-10 minutes)
+
+Evening:
+1. Go to Home tab
+2. Click "Refresh Clusters"
+3. Observe how new thoughts clustered with existing ones
+4. Spot emerging themes and connections
+```
+
+### Workflow 2: Deep Dive Analysis
+```
+1. Accumulate 20+ thoughts over several days
+2. Go to Home tab
+3. Click "Refresh Clusters"
+4. Examine the visualization:
+   - Which clusters are densest?
+   - What themes emerge?
+   - Any surprising connections?
+5. Switch to Feed tab
+6. Read the agent-generated insights
+7. Use for next creative session
+```
+
+### Workflow 3: Topic-Specific Exploration
+```
+1. Add 10+ thoughts about a specific topic
+2. They should cluster together automatically
+3. Hover over the cluster in Home tab
+4. Read the AI-generated cluster label
+5. Check Feed tab for synthesis across related thoughts
+6. Use the questions to drill deeper
+```
+
+---
+
+## 🤖 Agent Capabilities
+
+### QuestionAgent
+**Role**: Socratic questioning for deeper reflection
+
+**Input**: Brain dump text
+**Output**: 5 open-ended questions
+
+**Example**:
+```
+Brain Dump: "Why do I procrastinate on important tasks?"
+
+Generated Questions:
+1. What task are you procrastinating on right now?
+2. What emotion arises when you think about starting it?
+3. What would you do instead if you didn't procrastinate?
+4. What is the smallest first step you could take?
+5. What would happen if you started today?
+```
+
+### SearchAgent
+**Role**: Web search + synthesis or mock data generation
+
+**Input**: Brain dump text
+**Output**: Relevant context or summary
+
+**With Tavily API**:
+- Searches the web for related information
+- Synthesizes findings with LLM
+- Provides citations and context
+
+**Without Tavily API** (Demo Mode):
+- Generates plausible contextual information
+- Maintains consistency with the thought
+- Allows testing without API key
+
+### GenerationAgent
+**Role**: Cross-thought synthesis
+
+**Input**: Multiple related brain dumps (from same cluster)
+**Output**: Synthesized insight combining themes
+
+**Example**:
+```
+Related Dumps:
+- "Neural networks learn patterns"
+- "Our brains also learn from patterns"
+- "What if consciousness is pattern recognition?"
+
+Synthesis: These thoughts suggest that consciousness might emerge 
+from the brain's pattern recognition capabilities...
+```
+
+### FeedAgent
+**Role**: Orchestrates other agents for feed generation
+
+**Process**:
+1. Selects 5 most recent thoughts
+2. For each thought:
+   - Gets cluster assignment
+   - Calls SearchAgent for summary
+   - Calls QuestionAgent for reflection questions
+3. Formats as blog-style cards
+
+---
+
+## ⚙️ Configuration & Customization
+
+### Environment Variables (.env)
+
+Create `.env` file in project root:
+
+```bash
+# ============ REQUIRED ============
+
+# Neo4j Aura Connection
+NEO4J_URI=neo4j+ssc://your-instance-id.databases.neo4j.io
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your-super-secure-password
+
+# Google Gemini LLM API
+GOOGLE_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxx
+
+# ============ OPTIONAL ============
+
+# Tavily Web Search (for better summaries)
+TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxx
+
+# Perplexity API (alternative search)
+PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxx
+```
+
+### Optional: Streamlit Configuration
+
+Create `.streamlit/config.toml`:
+
+```toml
+[theme]
+primaryColor = "#4ECDC4"
+backgroundColor = "#0d1117"
+secondaryBackgroundColor = "#161b22"
+textColor = "#c9d1d9"
+
+[client]
+showErrorDetails = true
+
+[logger]
+level = "info"
+
+[server]
+port = 8501
+```
+
+---
+
+## 🔧 Development & Debugging
+
+### Running Locally
+```bash
+streamlit run app.py
+```
+
+### Clearing Database
+```bash
+python cleanup_db.py
+```
+
+### Neo4j Maintenance
+```bash
+python neo4j_maintenance.py
+```
+
+### Viewing Logs
+```bash
+# Terminal shows Streamlit logs
+# Check sidebar for spinner status during refresh
+```
+
+### Common Issues
+
+**Issue**: "Failed to connect to Neo4j"
+- Verify `.env` has correct URI, username, password
+- Check Neo4j Aura instance is running (console.neo4j.io)
+- Firewall: Neo4j needs outbound HTTPS (port 7687)
+
+**Issue**: "GOOGLE_API_KEY not found"
+- Ensure key is in `.env` file
+- Restart streamlit: `streamlit run app.py`
+
+**Issue**: Clusters not showing
+- Click "Refresh Clusters" in sidebar
+- Wait for spinner to finish (10-30 seconds)
+- Needs at least 2-3 thoughts for clustering
+
+**Issue**: Tavily search not working
+- Mock data is used if API key missing (expected)
+- Optional feature; not required for core functionality
+
+---
+
+## 📊 Performance Notes
+
+### Computational Complexity
+- **Adding 1 thought**: ~1 second
+- **Clustering N thoughts**: ~O(N) to O(N log N) depending on N
+  - 10 thoughts: ~2 seconds
+  - 100 thoughts: ~5-10 seconds
+  - 1000 thoughts: ~30-60 seconds
+- **LLM labeling**: ~2-5 seconds per cluster (depends on Gemini API latency)
+
+### Storage
+- Neo4j Free Tier: ~5 GB storage
+- Typical thought: ~500 bytes
+- Can store ~10 million thoughts theoretically
+
+### Scaling Recommendations
+- **Local testing**: ✅ Recommended
+- **Shared team use**: Consider dedicated Neo4j instance
+- **Large scale (10k+ thoughts)**: May need performance tuning (indexing, batching)
+
+---
+
+## 🎓 Learning Resources
+
+### Concepts Explained
+
+**Semantic Embeddings**
+- sentence-transformers model converts text to 384-dimensional vectors
+- Similar texts → similar vectors → can cluster together
+- Distance in vector space ≈ semantic similarity
+
+**HDBSCAN Clustering**
+- Density-based clustering (unlike K-means which needs K)
+- Automatically finds clusters of any shape
+- Robust to outliers (marks them as "noise")
+
+**Neo4j Graph Database**
+- Stores relationships as first-class citizens
+- Fast for relationship queries (unlike SQL)
+- Perfect for knowledge graphs and recommendations
+
+**LLMs for Labeling**
+- Google Gemini generates cluster labels from examples
+- LangChain chains handle prompt + LLM + parsing
+- Enables semantic understanding of cluster themes
+
+---
+
+## 📝 License
+
+See `LICENSE` file for details.
+
 ---
-title: Braindump Sanctuary
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: ✨ Transform scattered thoughts into insights.
-license: mit
+
+## 🤝 Contributing
+
+Found a bug or have a feature idea? 
+
+1. Check existing issues
+2. Create new issue with clear description
+3. (Optional) Submit PR with fix
+
+---
+
+## ❓ FAQ
+
+**Q**: Can I use this with a local Neo4j instance?
+**A**: Yes! Update `NEO4J_URI` to `neo4j://localhost:7687` in `.env`
+
+**Q**: What if I don't have a Tavily API key?
+**A**: That's fine! SearchAgent will generate mock data (demo mode)
+
+**Q**: Can I export all my thoughts?
+**A**: Use the table in Home tab or query Neo4j directly. Export feature coming soon.
+
+**Q**: How often should I click "Refresh Clusters"?
+**A**: After adding multiple new thoughts (5+), or when you want to see updated organization.
+
+**Q**: Is my data secure?
+**A**: Only you have your Neo4j password. Data is encrypted in transit and at rest on Neo4j Aura.
+
 ---
 
-# Welcome to Streamlit!
+## 🚀 Roadmap
+
+- [ ] Export functionality (CSV, JSON, markdown)
+- [ ] Thought search & filtering
+- [ ] Collaborative mode (multiple users)
+- [ ] Email digest of weekly summaries
+- [ ] Browser extension for quick capture
+- [ ] Mobile app
+- [ ] Advanced analytics dashboard
+
+[client]
+showErrorDetails = true
+```
+
+---
+
+## 🔧 Database Management
+
+### Re-calculate Clusters
+1. Go to Home tab
+2. Click 🔄 **Refresh** button
+3. Wait for spinner to complete
+
+### Clear Everything and Start Fresh
+1. Click 🗑️ **Clear All Dumps** in sidebar
+2. Confirm action
+3. Add new thoughts
+
+### Neo4j Maintenance
+Use the `neo4j_maintenance.py` script:
+```bash
+# Show database statistics
+python neo4j_maintenance.py stats
+
+# Remove duplicate brain dumps
+python neo4j_maintenance.py dedup
+
+# Clear all data (WARNING: Irreversible)
+python neo4j_maintenance.py clear
+```
+
+---
+
+## 📊 Performance Tips
+
+### Clustering
+- **Fast**: 3-20 dumps (< 5 seconds)
+- **Moderate**: 20-100 dumps (5-30 seconds)
+- **Slow**: 100+ dumps (> 30 seconds)
+- Use caching to avoid recomputing
+
+### API Usage
+- **Google Gemini**: Free tier allows ~60 requests/min
+- **Tavily Search**: Free tier allows ~100 searches/month
+- Set environment variables to enable features
+
+### Neo4j Query Performance
+- Dump and cluster lookups are indexed for fast retrieval
+- Embedding vectors cached in graph nodes
+- Knowledge graph relationships enable fast similarity searches
+
+---
+
+## 🐛 Troubleshooting
+
+### Neo4j Connection Error
+→ Verify your Aura instance is running: https://console.neo4j.io/
+→ Check `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` in `.env`
+→ Ensure your IP is allowlisted in Aura instance settings
+
+### "API Key not found" error
+→ Make sure `.env` file exists with `GOOGLE_API_KEY`
+→ Restart streamlit: `streamlit run app.py`
+
+### Clustering takes forever
+→ You might have 100+ dumps
+→ Only happens on first run or "Refresh"
+→ Consider batching cluster operations for large datasets
+
+### Feed cards showing mock data
+→ Your `TAVILY_API_KEY` isn't set
+→ Add it to `.env` and restart
+
+### "ModuleNotFoundError" for imports
+→ Missing dependencies: `pip install -r requirements.txt`
+→ Wrong Python version? Try `python3 -m pip install ...`
+
+---
+
+## 📚 Architecture Overview
+
+```
+braindump_core.py
+├── BrainDumpDB (Neo4j Graph Database)
+├── EmbeddingEngine (sentence-transformers)
+├── ClusterEngine (HDBSCAN + UMAP)
+└── Visualization (Plotly)
+
+agents.py
+├── QuestionAgent (Socratic questions)
+└── SearchAgent (Web search + synthesis)
+
+app.py
+├── Sidebar (Input + Navigation)
+├── Home Tab (Knowledge Graph + Table)
+├── Feed Tab (Blog-style cards)
+└── Helper Functions (Rendering)
+
+neo4j_maintenance.py
+├── Database statistics
+├── Deduplication
+└── Data cleanup
+```
+
+---
+
+## 🎯 Next Steps
+
+1. **Set up Neo4j Aura** instance at https://console.neo4j.io/
+2. **Add your first thought** via sidebar
+3. **Switch between Home and Feed** to see different views
+4. **Check back daily** to build your idea garden
+5. **Monitor performance** using `neo4j_maintenance.py stats`
+
+---
+
+## 💡 Tips
+
+- **Best for**: Capturing fleeting thoughts, finding patterns, exploring ideas
+- **Start small**: 5-10 thoughts to see clustering in action
+- **Use specificity**: "Why do dreams fade?" works better than "dreams"
+- **Review regularly**: Feed tab is great for morning/evening review
+- **Share clusters**: Screenshot Home tab to share your thinking
+
+---
+
+## 📝 Notes
+
+- All data stored locally in `braindump.db` (no cloud sync)
+- Embeddings cached in database (fast retrieval)
+- Cluster labels generated once and reused
+- Each brain dump timestamped automatically
+
+---
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+**Ready to catch your thoughts before they slip away!** 🧠✨
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+For issues or questions, check REFACTOR_SUMMARY.md or ARCHITECTURE.md

agents.py

@@ -0,0 +1,707 @@
+"""
+agents.py (Day 2)
+
+Contains the agentic logic for the Brain Dump Sanctuary.
+This file provides the classes that app.py imports.
+
+- QuestionAgent: Socratic question generation
+- PerspectiveAgent: Multi-angle analysis
+- SearchAgent: Web search + synthesis (MOCKED for Day 2)
+
+This file uses simple, direct LLM calls for the Day 2 demo.
+It is designed to be plug-and-play with app.py.
+
+Future Work: These classes can be refactored into nodes
+in a more complex LangGraph orchestration graph.
+"""
+
+import os
+import json
+import requests
+
+# We'll use Google Gemini as the LLM
+import google.generativeai as genai
+
+from dotenv import load_dotenv
+
+# Tavily for web search
+from tavily import TavilyClient
+
+# --- API Key Configuration ---
+# Add your "GOOGLE_API_KEY" to Kaggle secrets or environment variables.
+# Get your free key from: https://aistudio.google.com/app/apikey
+try:
+    load_dotenv()
+    # Fallback for local dev or other environments
+    API_KEY = os.getenv("GOOGLE_API_KEY")
+except Exception:
+    API_KEY = None
+
+if not API_KEY:
+    print("WARNING: GOOGLE_API_KEY not found. Please set it in your environment or Kaggle secrets.")
+    print("Get your free API key from: https://aistudio.google.com/app/apikey")
+    # Set a placeholder to avoid crashing, but calls will fail.
+    API_KEY = "YOUR_API_KEY_HERE"
+else:
+    # Configure Gemini with the API key
+    genai.configure(api_key=API_KEY)
+
+# --- Tavily API Key Configuration ---
+TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
+if not TAVILY_API_KEY:
+    print("WARNING: TAVILY_API_KEY not found. SearchAgent will use mock data.")
+    print("Get your API key from: https://app.tavily.com")
+    TAVILY_API_KEY = None
+
+# --- Perplexity API Key Configuration ---
+PERPLEXITY_API_KEY = os.getenv("PERPLEXITY_API_KEY")
+if not PERPLEXITY_API_KEY:
+    print("ℹ️ PERPLEXITY_API_KEY not found. Will use Tavily or mock data.")
+    print("Get your API key from: https://www.perplexity.ai/")
+    PERPLEXITY_API_KEY = None
+
+
+# ============== 1. Socratic Question Agent ==============
+
+class QuestionAgent:
+    """
+    Generates Socratic questions to expand on a vague idea.
+    """
+    def __init__(self, model="gemini-2.5-flash"):
+        self.model = model
+        self.system_prompt = """
+You are a Socratic tutor. A user has a vague brain dump idea. 
+Your goal is to generate 5 insightful, open-ended questions to help them 
+explore this idea, discover its core, and understand their own curiosity.
+
+- Do not answer the questions.
+- Provide ONLY the list of questions.
+- Return the questions as a JSON list of strings.
+
+Example:
+User Idea: "Why do we forget things we just read?"
+Your Response:
+[
+    "What kind of material do you find you forget most often?",
+    "What is your state of mind when you are reading?",
+    "Are you trying to memorize facts, or understand a concept?",
+    "What is the difference between remembering a fact and understanding an idea?",
+    "How does this relate to the 'forgetting curve'?"
+]
+"""
+
+    def generate_questions(self, idea: str) -> list[str]:
+        """Generates Socratic questions for a given idea."""
+        if API_KEY == "YOUR_API_KEY_HERE":
+             return ["Error: GOOGLE_API_KEY is not set.", "Please add it to your environment or Kaggle secrets."]
+
+        try:
+            # Create Gemini model
+            model = genai.GenerativeModel(
+                model_name=self.model,
+                generation_config={
+                    "temperature": 0.7,
+                    "response_mime_type": "application/json"
+                }
+            )
+            
+            # Combine system prompt and user input
+            prompt = f"{self.system_prompt}\n\nUser Idea: \"{idea}\""
+            
+            # Generate response
+            response = model.generate_content(prompt)
+            questions_json_string = response.text
+            questions = json.loads(questions_json_string)
+            
+            # The LLM might return a dict {"questions": [...]}, or just [...]
+            if isinstance(questions, dict):
+                # Try to find the list value
+                for key, value in questions.items():
+                    if isinstance(value, list):
+                        return value
+            elif isinstance(questions, list):
+                return questions
+            
+            return ["Error: Could not parse questions from LLM response."]
+
+        except Exception as e:
+            print(f"Error in QuestionAgent: {e}")
+            return [
+                "An error occurred while generating questions.",
+                "Is your API key set correctly?",
+                f"Details: {e}"
+            ]
+
+
+# ============== 2. Multi-Perspective Agent ==============
+
+class PerspectiveAgent:
+    """
+    Analyzes a controversial topic from multiple angles.
+    Can optionally use web search results for context.
+    """
+    def __init__(self, model="gemini-2.5-flash", search_agent=None):
+        self.model = model
+        self.search_agent = search_agent
+        self.system_prompt = """
+You are a multi-perspective analyst. A user has a topic,
+which may be controversial or nuanced.
+Your goal is to provide three distinct, concise viewpoints:
+1.  **Skeptical View:** The critical or cautious perspective.
+2.  **Optimistic View:** The positive or enthusiastic perspective.
+3.  **Nuanced View:** A balanced, synthetic view that includes trade-offs or a "third way".
+
+You MUST return a JSON object with exactly three keys:
+"skeptical", "optimistic", and "nuanced".
+Each value should be a short paragraph (2-4 sentences).
+"""
+
+    def analyze(self, topic: str) -> dict[str, str]:
+        """Analyzes a topic from multiple perspectives with optional web context."""
+        if API_KEY == "YOUR_API_KEY_HERE":
+            return {
+                "skeptical": "Error: GOOGLE_API_KEY not set.",
+                "optimistic": "Please add your API key to environment or Kaggle secrets.",
+                "nuanced": "The agent cannot run without an API key."
+            }
+
+        try:
+            # Get web context if search_agent is available
+            web_context = ""
+            sources = []
+            if self.search_agent and self.search_agent.use_real_search:
+                print(f"🌐 Fetching web context for multi-perspective analysis...")
+                articles = self.search_agent.get_relevant_articles(topic)
+                if articles:
+                    web_context = "\n\nRelevant Web Context:\n"
+                    for i, article in enumerate(articles, 1):
+                        web_context += f"{i}. {article['title']}: {article['snippet']}\n"
+                        sources.append(article)
+            
+            # Create Gemini model
+            model = genai.GenerativeModel(
+                model_name=self.model,
+                generation_config={
+                    "temperature": 0.7,
+                    "response_mime_type": "application/json"
+                }
+            )
+            
+            # Combine system prompt and user input with optional web context
+            prompt = f"{self.system_prompt}\n\nTopic: \"{topic}\"{web_context}"
+            
+            # Generate response
+            response = model.generate_content(prompt)
+            perspectives_json_string = response.text
+            perspectives = json.loads(perspectives_json_string)
+            
+            # Ensure the keys are always present to prevent errors in app.py
+            perspectives.setdefault('skeptical', 'No skeptical view generated.')
+            perspectives.setdefault('optimistic', 'No optimistic view generated.')
+            perspectives.setdefault('nuanced', 'No nuanced view generated.')
+            
+            # Add sources if available
+            if sources:
+                perspectives['sources'] = sources
+            
+            return perspectives
+            
+        except Exception as e:
+            print(f"Error in PerspectiveAgent: {e}")
+            return {
+                "skeptical": f"An error occurred: {e}",
+                "optimistic": "Please check your API key and model access.",
+                "nuanced": "The PerspectiveAgent failed to run."
+            }
+
+
+# ============== 3. Web Search Agent ==============
+
+class SearchAgent:
+    """
+    Real web search using Perplexity Sonar (preferred) or Tavily API + Gemini synthesis.
+    Falls back to mock data if API keys are missing.
+    """
+    def __init__(self):
+        self.use_perplexity = bool(PERPLEXITY_API_KEY)
+        self.use_tavily = bool(TAVILY_API_KEY) and not self.use_perplexity
+        self.use_real_search = self.use_perplexity or self.use_tavily
+        
+        if self.use_perplexity:
+            self.perplexity_api_key = PERPLEXITY_API_KEY
+            print("✅ Initialized SearchAgent with Perplexity Sonar API")
+        elif self.use_tavily:
+            self.tavily = TavilyClient(api_key=TAVILY_API_KEY)
+            self.llm = genai.GenerativeModel("gemini-2.5-flash")
+            print("✅ Initialized SearchAgent with Tavily API")
+        else:
+            print("⚠️ Initialized MOCK SearchAgent (no Perplexity or Tavily key)")
+    
+    def deep_dive(self, topic: str) -> dict:
+        """
+        Searches web using Perplexity Sonar or Tavily, then synthesizes.
+        Falls back to mock if no API key.
+        """
+        if not self.use_real_search:
+            return self._mock_search(topic)
+        
+        if self.use_perplexity:
+            return self._perplexity_search(topic)
+        else:
+            return self._tavily_search(topic)
+    
+    def _perplexity_search(self, topic: str) -> dict:
+        """Search using Perplexity Sonar API"""
+        try:
+            print(f"🔍 Searching Perplexity Sonar for: {topic}")
+            
+            url = "https://api.perplexity.ai/chat/completions"
+            headers = {
+                "Authorization": f"Bearer {self.perplexity_api_key}",
+                "Content-Type": "application/json"
+            }
+            
+            payload = {
+                "model": "sonar",
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "You are a helpful research assistant. Provide comprehensive, well-sourced answers."
+                    },
+                    {
+                        "role": "user",
+                        "content": f"Please provide a comprehensive summary about: {topic}"
+                    }
+                ],
+                "max_tokens": 1000,
+                "temperature": 0.7,
+                "top_p": 0.9
+            }
+            
+            response = requests.post(url, headers=headers, json=payload)
+            response.raise_for_status()
+            
+            data = response.json()
+            summary = data.get('choices', [{}])[0].get('message', {}).get('content', 'No summary generated')
+            
+            # Extract citations if available
+            sources = []
+            if 'citations' in data:
+                sources = [{"title": f"Source {i+1}", "url": "#", "snippet": cite} 
+                          for i, cite in enumerate(data['citations'][:5])]
+            
+            return {
+                "summary": summary,
+                "sources": sources
+            }
+            
+        except Exception as e:
+            print(f"❌ Perplexity search failed: {e}")
+            return {
+                "summary": f"Search failed: {str(e)}. Please check your Perplexity API key.",
+                "sources": []
+            }
+    
+    def _tavily_search(self, topic: str) -> dict:
+        """
+        Searches web using Tavily, then synthesizes with Gemini.
+        """
+        try:
+            # Step 1: Search with Tavily
+            print(f"🔍 Searching Tavily for: {topic}")
+            search_results = self.tavily.search(
+                query=topic,
+                max_results=5,
+                search_depth="advanced"
+            )
+            
+            # Step 2: Extract sources
+            sources = []
+            context = ""
+            for result in search_results.get('results', []):
+                sources.append({
+                    'title': result.get('title', 'Untitled'),
+                    'url': result.get('url', '#'),
+                    'snippet': result.get('content', '')[:200] + "..."
+                })
+                context += f"\n\n{result.get('content', '')}"
+            
+            # Step 3: Synthesize with Gemini
+            print(f"🤖 Synthesizing with Gemini...")
+            synthesis_prompt = f"""You are a research synthesizer. Based on the following web search results about "{topic}", 
+write a comprehensive 3-4 paragraph summary that:
+1. Answers the core question
+2. Highlights key findings and debates
+3. Cites different viewpoints if applicable
+
+Web Search Results:
+{context[:4000]}
+
+Provide ONLY the summary text, no preamble."""
+
+            response = self.llm.generate_content(synthesis_prompt)
+            summary = response.text
+            
+            return {
+                "summary": summary,
+                "sources": sources
+            }
+            
+        except Exception as e:
+            print(f"❌ Tavily search failed: {e}")
+            return {
+                "summary": f"Search failed: {str(e)}. Please check your Tavily API key.",
+                "sources": []
+            }
+    
+    def get_relevant_articles(self, topic: str, max_results: int = 3) -> list[dict]:
+        """
+        Gets top articles for a topic (used by PerspectiveAgent).
+        Returns: [{'title': str, 'url': str, 'snippet': str}, ...]
+        """
+        if not self.use_real_search:
+            return []
+        
+        try:
+            if self.use_perplexity:
+                print(f"📰 Fetching articles with Perplexity for: {topic}")
+                # Perplexity doesn't have a dedicated article fetch, use deep_dive results
+                result = self._perplexity_search(topic)
+                return result.get('sources', [])[:max_results]
+            else:
+                print(f"📰 Fetching articles for: {topic}")
+                search_results = self.tavily.search(
+                    query=topic,
+                    max_results=max_results,
+                    search_depth="basic"
+                )
+                
+                articles = []
+                for result in search_results.get('results', []):
+                    articles.append({
+                        'title': result.get('title', 'Untitled'),
+                        'url': result.get('url', '#'),
+                        'snippet': result.get('content', '')[:300] + "..."
+                    })
+                
+                return articles
+            
+        except Exception as e:
+            print(f"❌ Article fetch failed: {e}")
+            return []
+    
+    def _mock_search(self, topic: str) -> dict:
+        """Fallback mock implementation"""
+        print(f"🔍 MOCK SEARCH: Deep dive for '{topic}' (using hardcoded data)")
+        
+        # Simulate different responses for different topics
+        if "dream" in topic.lower():
+            return {
+                "summary": (
+                    "Dreams are a complex neurological phenomenon, primarily occurring during "
+                    "REM sleep. Research suggests they are crucial for memory consolidation, "
+                    "emotional regulation, and problem-solving. The 'fading' "
+                    "is attributed to the brain's different neurochemical state during sleep, "
+                    "which is not optimized for encoding new memories."
+                ),
+                "sources": [
+                    {"title": "The Science of Dreaming - Scientific American", "url": "https://www.scientificamerican.com/article/the-science-of-dreaming/"},
+                    {"title": "Why We Dream - Psychology Today", "url": "https://www.psychologytoday.com/us/basics/dreaming"}
+                ]
+            }
+        elif "llm" in topic.lower():
+            return {
+                "summary": (
+                    "The debate on LLM 'understanding' is central to AI research. "
+                    "One view holds they are 'stochastic parrots,' brilliantly matching "
+                    "statistical patterns without true comprehension. "
+                    "The opposing view suggests that at their scale, these models "
+                    "develop emergent, internal world models, representing a new "
+                    "form of understanding."
+                ),
+                "sources": [
+                    {"title": "On the Dangers of Stochastic Parrots - FAccT '21", "url": "https://dl.acm.org/doi/10.1145/3442188.3445922"},
+                    {"title": "Sparks of AGI: Early experiments with GPT-4", "url": "https://arxiv.org/abs/2303.12712"}
+                ]
+            }
+        else:
+            return {
+                "summary": (
+                    f"This is a mock summary about '{topic}'. This agent successfully simulated a "
+                    "web search. In a real application, this text would be "
+                    "dynamically generated by an LLM based on live search results "
+                    "from a tool like Tavily or SerpAPI."
+                ),
+                "sources": [
+                    {"title": "Mock Source 1 - Wikipedia", "url": "https://en.wikipedia.org/wiki/Main_Page"},
+                    {"title": "Mock Source 2 - Example.com", "url": "https://example.com"}
+                ]
+            }
+
+# --- How to refactor to LangGraph (Future Work) ---
+"""
+To implement your full "LangGraph" vision, you would:
+
+1.  Define a State:
+    class BrainDumpState(TypedDict):
+        topic: str
+        socratic_questions: list[str]
+        perspectives: dict
+        deep_dive: dict
+
+2.  Create Nodes:
+    - Each agent's method (e.g., `generate_questions`) becomes a node.
+    - def question_node(state: BrainDumpState):
+    -   questions = QuestionAgent().generate_questions(state['topic'])
+    -   return {"socratic_questions": questions}
+    - ... (similar nodes for perspective_node and search_node)
+
+3.  Build the Graph:
+    - workflow = StateGraph(BrainDumpState)
+    - workflow.add_node("socratic", question_node)
+    - workflow.add_node("perspectives", perspective_node)
+    - workflow.add_node("search", search_node)
+    - workflow.set_entry_point("socratic") # or a router
+    - workflow.add_edge("socratic", "perspectives")
+    - workflow.add_edge("perspectives", "search")
+    - workflow.add_edge("search", END)
+
+4.  Compile & Run:
+    - app = workflow.compile()
+    - # In app.py, you'd call:
+    - # results = app.invoke({"topic": "Why do we dream?"})
+    - # And then display results['socratic_questions'], etc.
+    
+This simple class-based approach is used for the Day 2 demo
+as it directly matches your existing app.py implementation.
+"""
+
+
+# ============== 4. Feed Agent (using Perplexity Sonar) ==============
+
+class FeedAgent:
+    """
+    Generates AI-powered summaries for feed cards using Perplexity Sonar.
+    If Perplexity is not available, falls back to SearchAgent.
+    Also fetches relevant images using Tavily image search.
+    """
+    def __init__(self, search_agent=None):
+        self.search_agent = search_agent
+        self.use_perplexity = bool(PERPLEXITY_API_KEY)
+        self.perplexity_api_key = PERPLEXITY_API_KEY
+        self.tavily_client = TavilyClient(api_key=TAVILY_API_KEY) if TAVILY_API_KEY else None
+        
+        if self.use_perplexity:
+            print("✅ Initialized FeedAgent with Perplexity Sonar")
+        else:
+            print("ℹ️ FeedAgent will use SearchAgent for summaries")
+        
+        if self.tavily_client:
+            print("📸 Initialized FeedAgent with Tavily Image Search")
+        else:
+            print("⚠️ Tavily API key not configured. Image search disabled.")
+    
+    def generate_summary(self, topic: str) -> dict:
+        """
+        Generate a comprehensive summary using Perplexity Sonar.
+        Returns: {"summary": str, "sources": list}
+        """
+        if self.use_perplexity:
+            return self._perplexity_summary(topic)
+        elif self.search_agent:
+            return self.search_agent.deep_dive(topic)
+        else:
+            return {
+                "summary": "Unable to generate summary. Please configure Perplexity or Tavily API.",
+                "sources": []
+            }
+    
+    def _perplexity_summary(self, topic: str) -> dict:
+        """Generate summary using Perplexity Sonar API"""
+        try:
+            print(f"🧠 Generating Sonar summary for: {topic}")
+            
+            url = "https://api.perplexity.ai/chat/completions"
+            headers = {
+                "Authorization": f"Bearer {self.perplexity_api_key}",
+                "Content-Type": "application/json"
+            }
+            
+            payload = {
+                "model": "sonar",
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": """You are a brilliant synthesizer of knowledge. Given a brain dump topic, 
+provide a comprehensive yet concise summary that:
+1. Explains the core concept clearly
+2. Provides practical insights
+3. Connects to broader contexts
+4. Sparks further curiosity
+
+Keep the tone engaging and thought-provoking."""
+                    },
+                    {
+                        "role": "user",
+                        "content": f"Provide a comprehensive summary about this brain dump topic: {topic}"
+                    }
+                ],
+                "max_tokens": 1500,
+                "temperature": 0.7,
+                "top_p": 0.9,
+                "search_domain_filter": ["perplexity.com"]
+            }
+            
+            response = requests.post(url, headers=headers, json=payload)
+            response.raise_for_status()
+            
+            data = response.json()
+            summary = data.get('choices', [{}])[0].get('message', {}).get('content', 'No summary generated')
+            
+            # Extract citations if available
+            sources = []
+            if 'citations' in data:
+                sources = [{"title": f"Source {i+1}", "url": "#", "snippet": cite} 
+                          for i, cite in enumerate(data['citations'][:3])]
+            
+            return {
+                "summary": summary,
+                "sources": sources
+            }
+            
+        except Exception as e:
+            print(f"❌ Perplexity summary generation failed: {e}")
+            # Fallback to SearchAgent if available
+            if self.search_agent:
+                print("Falling back to SearchAgent...")
+                return self.search_agent.deep_dive(topic)
+            
+            return {
+                "summary": f"Error generating summary: {str(e)}",
+                "sources": []
+            }
+    
+    def search_images(self, topic: str, max_results: int = 3) -> list[str]:
+        """
+        Search for relevant images using Tavily image search API.
+        
+        Args:
+            topic: The topic to search for images
+            max_results: Maximum number of images to return (default: 3)
+            
+        Returns:
+            List of image URLs (up to max_results)
+        """
+        if not self.tavily_client:
+            print("⚠️ Tavily API key not configured. Cannot search for images.")
+            return []
+        
+        try:
+            print(f"📸 Searching for images related to: {topic}")
+            
+            # Use Tavily to search for images
+            response = self.tavily_client.search(
+                query=topic,
+                max_results=max_results,
+                include_images=True
+            )
+            
+            # Extract image URLs from results
+            image_urls = []
+            
+            # Try to extract images from the response
+            if 'images' in response:
+                for img in response['images'][:max_results]:
+                    if isinstance(img, dict) and 'url' in img:
+                        image_urls.append(img['url'])
+                    elif isinstance(img, str):
+                        image_urls.append(img)
+            
+            # If no images found in dedicated images field, try results
+            if not image_urls and 'results' in response:
+                for result in response['results'][:max_results]:
+                    if isinstance(result, dict) and 'image' in result:
+                        image_urls.append(result['image'])
+            
+            print(f"✓ Found {len(image_urls)} relevant images")
+            return image_urls[:max_results]
+            
+        except Exception as e:
+            print(f"❌ Image search failed: {e}")
+            return []
+
+
+# ============== 5. Brain Dump Generation Agent ==============
+
+class GenerationAgent:
+    """
+    Generates creative braindumps based on a cluster's theme and entries.
+    Takes a cluster name and list of entries, uses Gemini to synthesize
+    a new braindump that fits the cluster and would be interesting to read.
+    """
+    def __init__(self, model="gemini-2.5-flash"):
+        self.model = model
+        self.system_prompt = """
+You are a creative brainstorming agent. You've been given a cluster of related thoughts/brain dumps,
+along with the cluster's theme.
+
+Your task is to generate ONE new, engaging brain dump entry that:
+1. Fits naturally with the theme and existing entries
+2. Is inspired by the existing entries but presents a NEW angle or question
+3. Is concise (1-2 sentences), matching the style of the existing entries
+4. Introduces something the user might find interesting to explore
+5. Does NOT simply repeat or combine existing entries
+
+Generate ONLY the new brain dump text itself - no preamble, no explanation.
+Just the thoughtful question or observation that belongs in this cluster.
+"""
+
+    def generate_braindump(self, cluster_name: str, entries: list[str]) -> str:
+        """
+        Generates a new braindump for a cluster.
+        
+        Args:
+            cluster_name: The name/label of the cluster (e.g., "Dreams and Consciousness")
+            entries: List of existing brain dump texts in this cluster
+            
+        Returns:
+            Generated brain dump text as a string
+        """
+        if API_KEY == "YOUR_API_KEY_HERE":
+            return "Error: GOOGLE_API_KEY is not set. Please add it to your environment."
+
+        try:
+            # Create Gemini model
+            model = genai.GenerativeModel(
+                model_name=self.model,
+                generation_config={
+                    "temperature": 0.8,  # Higher temperature for more creativity
+                }
+            )
+            
+            # Format entries for the prompt
+            entries_str = "\n".join([f"- {entry}" for entry in entries])
+            
+            # Build the prompt
+            prompt = f"""{self.system_prompt}
+
+Cluster Theme: "{cluster_name}"
+
+Existing entries in this cluster:
+{entries_str}
+
+Generate a new, creative brain dump entry that fits this cluster:"""
+            
+            # Generate response
+            response = model.generate_content(prompt)
+            generated_text = response.text.strip()
+            
+            # Clean up any extra quotes or markers
+            if generated_text.startswith('"') and generated_text.endswith('"'):
+                generated_text = generated_text[1:-1]
+            
+            return generated_text
+            
+        except Exception as e:
+            print(f"Error in GenerationAgent: {e}")
+            return f"Error generating braindump: {str(e)}"

app.py

@@ -0,0 +1,628 @@
+"""
+Brain Dump Sanctuary - Day 2 Complete System
+Includes: Streamlit UI + LangGraph Agent + Multi-Perspective Analysis
+
+File structure:
+braindump_sanctuary/
+├── app.py (THIS FILE - run with: streamlit run app.py)
+├── agents.py (LangGraph workflows)
+├── braindump_core.py (from Day 1)
+└── requirements.txt
+"""
+
+# ============== app.py - MAIN STREAMLIT APP ==============
+import streamlit as st
+import sys
+from datetime import datetime
+import pytz
+import plotly.graph_objects as go
+import numpy as np
+import pandas as pd
+from fuzzywuzzy import fuzz
+
+# Import Day 1 components
+from braindump_core import BrainDumpDB, EmbeddingEngine, ClusterEngine, create_knowledge_graph
+
+# Import Day 2 components
+from agents import QuestionAgent, SearchAgent, GenerationAgent, FeedAgent
+
+# Page config
+st.set_page_config(
+    page_title="Brain Dump Sanctuary",
+    page_icon="🧠",
+    layout="wide"
+)
+
+# Initialize session state
+if 'db' not in st.session_state:
+    st.session_state.db = BrainDumpDB()
+if 'embedder' not in st.session_state:
+    st.session_state.embedder = EmbeddingEngine()
+if 'clusterer' not in st.session_state:
+    st.session_state.clusterer = ClusterEngine(min_cluster_size=2)
+if 'search_agent' not in st.session_state:
+    st.session_state.search_agent = SearchAgent()
+if 'question_agent' not in st.session_state:
+    st.session_state.question_agent = QuestionAgent()
+if 'generation_agent' not in st.session_state:
+    st.session_state.generation_agent = GenerationAgent()
+if 'feed_agent' not in st.session_state:
+    st.session_state.feed_agent = FeedAgent(search_agent=st.session_state.search_agent)
+
+# Sidebar
+with st.sidebar:
+    st.title("🧠 Brain Dump Sanctuary")
+    st.markdown("Transform stale lists into actionable curiosity")
+    
+    st.divider()
+    
+    # Tab Switcher
+    tab_selection = st.radio(
+        "Navigate",
+        ["Home", "Feed"],
+        label_visibility="collapsed"
+    )
+    
+    st.divider()
+    
+    # Add new brain dump
+    st.subheader("💭 New Brain Dump")
+    
+    # Use a unique key that changes when we clear
+    if 'input_key' not in st.session_state:
+        st.session_state.input_key = 0
+    
+    new_dump = st.text_area(
+        "What's on your mind?",
+        placeholder="Why do dreams feel so real?",
+        height=100,
+        label_visibility="collapsed",
+        key=f"dump_input_{st.session_state.input_key}"
+    )
+    
+    col1, col2 = st.columns([3, 1])
+    with col1:
+        add_clicked = st.button("Add to Sanctuary", type="primary", use_container_width=True)
+    with col2:
+        clear_clicked = st.button("Clear", use_container_width=True)
+    
+    if add_clicked:
+        if new_dump.strip():
+            if not st.session_state.get('adding', False):
+                st.session_state.adding = True
+                dump_id, is_duplicate = st.session_state.db.add_dump(new_dump.strip())
+                st.session_state.input_key += 1
+                if is_duplicate:
+                    st.warning("This thought already exists in your sanctuary! 🔄")
+                else:
+                    st.success("Added! ✨")
+                st.rerun()
+            else:
+                st.session_state.adding = False
+        else:
+            st.error("Can't add empty thought!")
+    
+    if clear_clicked:
+        if not st.session_state.get('clearing_input', False):
+            st.session_state.clearing_input = True
+            st.session_state.input_key += 1
+            st.rerun()
+        else:
+            st.session_state.clearing_input = False
+    
+    st.divider()
+    
+    # Actions
+    st.subheader("⚙️ Actions")
+    
+    if st.button("🔄 Refresh Clusters", use_container_width=True):
+        st.info("Clusters will refresh on the Home tab")
+    
+    if st.button("🗑️ Clear All Dumps", use_container_width=True):
+        if not st.session_state.get('clearing', False):
+            st.session_state.clearing = True
+            # Clear all dumps and clusters from Neo4j
+            with st.session_state.db.driver.session() as session:
+                session.run("MATCH (d:Dump) DETACH DELETE d")
+                session.run("MATCH (c:Cluster) DETACH DELETE c")
+            st.session_state.input_key = 0
+            st.success("All dumps cleared!")
+            st.rerun()
+        else:
+            st.session_state.clearing = False
+    
+    # Stats
+    st.divider()
+    dumps = st.session_state.db.get_all_dumps()
+    st.metric("Total Brain Dumps", len(dumps))
+
+# ============== HELPER FUNCTIONS ==============
+
+def render_brain_dump_table(dumps, cluster_labels_map):
+    """Render brain dumps as a table with cluster labels and timestamps"""
+    if not dumps:
+        st.info("No brain dumps yet.")
+        return
+    
+    # Prepare data for table
+    table_data = []
+    for dump_id, text, cluster_id, created_at in dumps:  # Already sorted by DESC in get_all_dumps()
+        cluster_label = "Unclustered"
+        if cluster_id is not None and cluster_id != -1 and cluster_id in cluster_labels_map:
+            cluster_label = cluster_labels_map[cluster_id]['label']
+        
+        # Format timestamp - handle Neo4j datetime objects and convert to IST
+        if created_at:
+            try:
+                # Neo4j returns a neo4j.time.DateTime object
+                # Convert to IST (Indian Standard Time: UTC+5:30)
+                ist = pytz.timezone('Asia/Kolkata')
+                
+                # Parse the datetime string if needed
+                if isinstance(created_at, str):
+                    # Try to parse ISO format datetime
+                    dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                else:
+                    # Assume it's a datetime object
+                    dt = created_at
+                
+                # Make it timezone-aware if it isn't already
+                if dt.tzinfo is None:
+                    # Assume UTC if no timezone
+                    dt = pytz.UTC.localize(dt)
+                
+                # Convert to IST
+                dt_ist = dt.astimezone(ist)
+                
+                # Format as readable string
+                created_at_str = dt_ist.strftime("%d %b %Y, %I:%M %p IST")
+            except Exception as e:
+                print(f"Timestamp conversion error: {e}")
+                created_at_str = str(created_at) if created_at else "Unknown"
+        else:
+            created_at_str = "Unknown"
+        
+        table_data.append({
+            "Brain Dump": text,
+            "Cluster Label": cluster_label,
+            "Created At": created_at_str
+        })
+    
+    df = pd.DataFrame(table_data)
+    st.dataframe(df, use_container_width=True, hide_index=True)
+
+
+def render_feed_card(dump_id, text, cluster_id, cluster_labels_map):
+    """Render a single blog-style card for a brain dump with agent outputs"""
+    with st.container(border=True):
+        # Title
+        st.markdown(f"### 💭 {text}")
+        
+        # Cluster label badge
+        if cluster_id is not None and cluster_id != -1 and cluster_id in cluster_labels_map:
+            cluster_label = cluster_labels_map[cluster_id]['label']
+            st.markdown(f"🏷️ **{cluster_label}**")
+        
+        st.divider()
+        
+        # Check if we have cached feed data
+        cached_data = st.session_state.db.get_feed_cache(dump_id)
+        
+        if cached_data:
+            # Use cached summary and questions
+            st.markdown("**Summary:**")
+            st.write(cached_data['summary'])
+            questions = cached_data['questions']
+            image_urls = cached_data.get('image_urls', [])
+            
+            # If cached data exists but images are missing, generate them
+            if not image_urls:
+                with st.spinner("📸 Fetching related images..."):
+                    try:
+                        image_urls = st.session_state.feed_agent.search_images(text, max_results=3)
+                        # Update cache with new image URLs
+                        st.session_state.db.save_feed_cache(dump_id, cached_data['summary'], questions, image_urls)
+                    except Exception as e:
+                        print(f"Error searching for images: {str(e)}")
+                        image_urls = []
+        else:
+            # Generate summary using Feed Agent
+            with st.spinner("🧠 Generating Sonar summary and images..."):
+                try:
+                    result = st.session_state.feed_agent.generate_summary(text)
+                    summary = result['summary']
+                    st.markdown("**Summary:**")
+                    st.write(summary)
+                    
+                    # Generate questions
+                    questions = st.session_state.question_agent.generate_questions(text)
+                    
+                    # Search for related images
+                    image_urls = st.session_state.feed_agent.search_images(text, max_results=3)
+                    
+                    # Cache summary, questions, and images
+                    st.session_state.db.save_feed_cache(dump_id, summary, questions, image_urls)
+                except Exception as e:
+                    st.error(f"Error generating summary: {str(e)}")
+                    summary = "Unable to generate summary. Please try again."
+                    questions = []
+                    image_urls = []
+        
+        # Display images if available
+        if image_urls:
+            st.divider()
+            st.markdown("**Related Images:**")
+            cols = st.columns(min(3, len(image_urls)))  # Create up to 3 columns
+            for idx, image_url in enumerate(image_urls[:3]):
+                with cols[idx]:
+                    try:
+                        st.image(image_url, use_container_width=True)
+                    except Exception as e:
+                        st.caption(f"Could not load image: {image_url}")
+        
+        st.divider()
+        
+        # Display questions (either cached or just generated)
+        st.markdown("**Questions for Reflection:**")
+        if questions:
+            for i, q in enumerate(questions, 1):
+                st.markdown(f"{i}. {q}")
+        else:
+            st.info("No questions available for this brain dump.")
+
+
+def render_home():
+    """Render the Home tab with cluster map, text input, and brain dump table"""
+    st.title("🧠 Brain Dump Sanctuary")
+    st.markdown("*Where racing thoughts become structured curiosity*")
+    
+    dumps = st.session_state.db.get_all_dumps()
+    
+    if len(dumps) == 0:
+        st.info("👋 Welcome! Add your first brain dump using the sidebar.")
+        
+        with st.expander("🎯 Try these example dumps"):
+            examples = [
+                "Why do dreams feel so real but fade so quickly?",
+                "How does quantum entanglement actually work?",
+                "Are LLMs actually understanding or just pattern matching?",
+                "What causes the smell of rain on dry ground?",
+                "Why does time feel faster as we age?",
+            ]
+            for ex in examples:
+                if st.button(f"Add: {ex}", key=ex):
+                    dump_id, is_duplicate = st.session_state.db.add_dump(ex)
+                    st.rerun()
+    else:
+        # Cluster Map Section
+        st.subheader("🗺️ Semantic Cluster Map")
+        
+        if len(dumps) < 3:
+            st.warning("⚠️ Add at least 3 brain dumps to see meaningful clusters")
+        else:
+            try:
+                col1, col2 = st.columns([4, 1])
+                with col2:
+                    force_refresh = st.button("🔄 Refresh", help="Recalculate embeddings and clusters")
+                
+                # Check if embeddings already exist for all dumps
+                existing_embeddings = st.session_state.db.get_embeddings()
+                existing_ids = {emb[0] for emb in existing_embeddings}
+                all_dump_ids = {d[0] for d in dumps}
+                
+                # Check if cluster labels already exist
+                existing_labels = st.session_state.db.get_all_cluster_labels()
+                
+                # Check if reducer exists (used for cached path)
+                has_reducer = st.session_state.clusterer.reducer is not None
+                
+                # Only recalculation if we have new dumps without embeddings OR force refresh OR no reducer yet
+                need_recalculation = force_refresh or not (existing_ids >= all_dump_ids) or not has_reducer
+                
+                if need_recalculation:
+                    with st.spinner("Generating embeddings and clustering..."):
+                        # Generate embeddings
+                        texts = [d[1] for d in dumps]
+                        embeddings = st.session_state.embedder.embed(texts)
+                        
+                        # Update embeddings in DB
+                        for i, (dump_id, _, _, _) in enumerate(dumps):
+                            st.session_state.db.update_embedding(dump_id, embeddings[i])
+                        
+                        # Cluster
+                        clusters, coords_2d = st.session_state.clusterer.fit_predict(embeddings)
+                        
+                        # Track which clusters have changed
+                        clusters_with_changes = set()
+                        
+                        # Check for cluster ID changes for each dump
+                        for i, (dump_id, _, old_cluster_id, _) in enumerate(dumps):
+                            new_cluster_id = clusters[i]
+                            if old_cluster_id != new_cluster_id:
+                                clusters_with_changes.add(new_cluster_id)
+                                if old_cluster_id is not None and old_cluster_id != -1:
+                                    clusters_with_changes.add(old_cluster_id)
+                        
+                        # Update clusters in DB
+                        for i, (dump_id, _, _, _) in enumerate(dumps):
+                            st.session_state.db.update_cluster(dump_id, clusters[i])
+                        
+                        # Auto-generate cluster labels for new clusters or changed clusters
+                        cluster_labels_dict = {}
+                        unique_clusters = set(clusters) - {-1}
+                        
+                        if unique_clusters:
+                            with st.spinner("Generating cluster labels with Gemini..."):
+                                for cluster_id in unique_clusters:
+                                    # Re-label if cluster is new OR if it had changes
+                                    if cluster_id not in existing_labels or cluster_id in clusters_with_changes:
+                                        cluster_dumps = [dumps[i][1] for i in range(len(dumps)) if clusters[i] == cluster_id]
+                                        label = st.session_state.clusterer.generate_cluster_label(cluster_dumps)
+                                        cluster_labels_dict[cluster_id] = label
+                                        st.session_state.db.save_cluster_label(cluster_id, label)
+                                    else:
+                                        cluster_labels_dict[cluster_id] = existing_labels[cluster_id]['label']
+                        
+                        # Generate and cache feed data for new/uncached dumps
+                        with st.spinner("Generating feed summaries and questions..."):
+                            for i, (dump_id, text, _, _) in enumerate(dumps):
+                                # Check if feed cache already exists
+                                if not st.session_state.db.get_feed_cache(dump_id):
+                                    try:
+                                        # Generate summary
+                                        summary_result = st.session_state.feed_agent.generate_summary(text)
+                                        summary = summary_result['summary']
+                                        
+                                        # Generate questions
+                                        questions = st.session_state.question_agent.generate_questions(text)
+                                        
+                                        # Cache both
+                                        st.session_state.db.save_feed_cache(dump_id, summary, questions)
+                                    except Exception as e:
+                                        print(f"Warning: Could not generate feed cache for {dump_id}: {e}")
+                                        # Continue without caching for this dump
+                else:
+                    # Use existing embeddings and clusters
+                    st.info("📦 Using cached embeddings and clusters")
+                    
+                    # Load existing embeddings
+                    embeddings_list = []
+                    for dump_id, _, _, _ in dumps:
+                        matching_emb = next((emb[1] for emb in existing_embeddings if emb[0] == dump_id), None)
+                        if matching_emb is not None:
+                            embeddings_list.append(matching_emb)
+                    
+                    embeddings = np.array(embeddings_list)
+                    
+                    # Get clusters from database
+                    clusters = np.array([d[2] if d[2] is not None else -1 for d in dumps])
+                    
+                    # Get 2D coordinates for visualization
+                    coords_2d = st.session_state.clusterer.reducer.fit_transform(embeddings)
+                    
+                    # Load existing cluster labels
+                    cluster_labels_dict = {k: v['label'] for k, v in existing_labels.items()}
+                    unique_clusters = set(clusters) - {-1}
+                
+                # Visualize with labels
+                fig = create_knowledge_graph(dumps, coords_2d, clusters, cluster_labels_dict, embeddings)
+                st.plotly_chart(fig, use_container_width=True)
+                        
+            except Exception as e:
+                st.error(f"❌ Clustering error: {str(e)}")
+                if st.checkbox("Show technical details"):
+                    st.exception(e)
+        
+        st.divider()
+        
+        # Consolidated Cluster Generation Section
+        st.subheader("🧬 Generate New Brain Dumps for All Clusters")
+        
+        col1, col2 = st.columns([4, 1])
+        with col1:
+            st.markdown("*Generate one new braindump for each cluster in a single click*")
+        
+        with col2:
+            if st.button("✨ Generate All", key="gen_all_clusters", help="Generate a new braindump for each cluster", type="primary"):
+                try:
+                    # Get all clusters with their dumps
+                    all_cluster_labels = st.session_state.db.get_all_cluster_labels()
+                    
+                    if all_cluster_labels:
+                        generated_count = 0
+                        failed_clusters = []
+                        
+                        with st.spinner("🤖 Generating braindumps for all clusters..."):
+                            generated_dumps = []  # Track generated dumps and their cluster IDs
+                            
+                            for cluster_id, cluster_info in all_cluster_labels.items():
+                                cluster_label = cluster_info['label']
+                                
+                                # Skip clusters with None label
+                                if cluster_label is None:
+                                    failed_clusters.append(f"Cluster {cluster_id} (no label)")
+                                    continue
+                                
+                                # Get dumps in this cluster
+                                cluster_dumps = st.session_state.db.get_cluster_dumps(cluster_id)
+                                if cluster_dumps:
+                                    cluster_dump_texts = [d[1] for d in cluster_dumps]
+                                    
+                                    try:
+                                        # Generate the braindump
+                                        generated_text = st.session_state.generation_agent.generate_braindump(
+                                            cluster_name=cluster_label,
+                                            entries=cluster_dump_texts
+                                        )
+                                        
+                                        # Check if there was an error
+                                        if not generated_text.startswith("Error"):
+                                            # Add to database with cluster assignment
+                                            new_dump_id, is_duplicate = st.session_state.db.add_generated_dump(generated_text, cluster_id)
+                                            
+                                            if not is_duplicate:
+                                                # Compute embedding for the generated dump immediately
+                                                # so it doesn't trigger a full recalculation on rerun
+                                                generated_embedding = st.session_state.embedder.embed([generated_text])[0]
+                                                st.session_state.db.update_embedding(new_dump_id, generated_embedding)
+                                                
+                                                generated_dumps.append((new_dump_id, generated_text, cluster_id))
+                                                generated_count += 1
+                                            else:
+                                                # Duplicate found, skip this generated dump
+                                                pass
+                                        else:
+                                            failed_clusters.append(cluster_label)
+                                    except Exception as e:
+                                        print(f"Error generating for {cluster_label}: {e}")
+                                        failed_clusters.append(cluster_label)
+                        
+                        # Show results
+                        if generated_count > 0:
+                            st.success(f"✨ Generated {generated_count} new brain dump{'s' if generated_count != 1 else ''}!")
+                        
+                        if failed_clusters:
+                            st.warning(f"⚠️ Could not generate for: {', '.join(failed_clusters)}")
+                        
+                        if generated_count > 0:
+                            st.rerun()
+                    else:
+                        st.info("💡 No clusters available yet.")
+                except Exception as e:
+                    st.error(f"Error generating braindumps: {str(e)}")
+        
+        st.divider()
+        
+        # Brain Dump Table Section
+        st.subheader("📋 All Brain Dumps")
+        cluster_labels_map = st.session_state.db.get_all_cluster_labels()
+        render_brain_dump_table(dumps, cluster_labels_map)
+
+
+def render_feed():
+    """Render the Feed tab with blog-style cards for 5 most recent brain dumps"""
+    st.title("📰 Feed")
+    st.markdown("*Agent-generated insights for your most recent thoughts*")
+    
+    dumps = st.session_state.db.get_all_dumps()
+    
+    if len(dumps) == 0:
+        st.info("👋 No brain dumps yet. Add one using the sidebar to get started!")
+    else:
+        cluster_labels_map = st.session_state.db.get_all_cluster_labels()
+        
+        # Initialize search mode state if not exists
+        if 'search_mode' not in st.session_state:
+            st.session_state.search_mode = False
+        if 'selected_dump_id' not in st.session_state:
+            st.session_state.selected_dump_id = None
+        
+        # Search and filter section
+        col1, col2 = st.columns([4, 1])
+        
+        with col1:
+            search_query = st.text_input(
+                "🔍 Search brain dumps",
+                placeholder="Type to search...",
+                key="feed_search",
+                help="Search using fuzzy matching (handles typos)"
+            )
+        
+        # Perform fuzzy matching using fuzzywuzzy
+        suggestions = []
+        if search_query.strip():
+            # Calculate fuzzy match score for each dump
+            for dump_id, text, cluster_id, created_at in dumps:
+                # Use first 100 chars of text for matching
+                match_text = text[:100]
+                # Use token_sort_ratio for better matching with word order variations
+                score = fuzz.token_sort_ratio(search_query.lower(), match_text.lower())
+                suggestions.append({
+                    'dump_id': dump_id,
+                    'text': text,
+                    'cluster_id': cluster_id,
+                    'score': score,
+                    'match_text': match_text
+                })
+            
+            # Sort by score (higher = better match) and take top 8
+            suggestions = sorted(suggestions, key=lambda x: x['score'], reverse=True)[:8]
+            
+            if suggestions:
+                st.write(f"**Found {len(suggestions)} best matches:**")
+                
+                # Create dropdown options (truncated text)
+                suggestion_texts = [
+                    s['text'][:70] + "..." if len(s['text']) > 70 else s['text'] 
+                    for s in suggestions
+                ]
+                
+                # Show suggestions as a dropdown with match score
+                selected_idx = st.selectbox(
+                    "Select a brain dump",
+                    range(len(suggestions)),
+                    format_func=lambda i: f"({suggestions[i]['score']}%) {suggestion_texts[i]}",
+                    key="feed_suggestions_dropdown",
+                    help="Suggestions ranked by relevance (higher % = better match)"
+                )
+                
+                if selected_idx is not None:
+                    st.session_state.search_mode = True
+                    st.session_state.selected_dump_id = suggestions[selected_idx]['dump_id']
+            else:
+                st.warning(f"No brain dumps found for '{search_query}'")
+        else:
+            # No search query - clear search mode
+            st.session_state.search_mode = False
+            st.session_state.selected_dump_id = None
+        
+        st.divider()
+        
+        # Display selected dump or recent dumps
+        if st.session_state.search_mode and st.session_state.selected_dump_id:
+            # Show single selected dump with back button
+            col1, col2 = st.columns([4, 1])
+            
+            with col2:
+                if st.button("← Back to Feed", key="back_to_feed"):
+                    st.session_state.search_mode = False
+                    st.session_state.selected_dump_id = None
+                    st.rerun()
+            
+            # Find the selected dump
+            selected_dump = next(
+                (d for d in dumps if d[0] == st.session_state.selected_dump_id),
+                None
+            )
+            
+            if selected_dump:
+                dump_id, text, cluster_id, created_at = selected_dump
+                st.markdown("### Single Brain Dump View")
+                render_feed_card(dump_id, text, cluster_id, cluster_labels_map)
+        else:
+            # Show 5 most recent dumps (default view)
+            recent_dumps = dumps[:5]
+            st.markdown(f"Showing **{len(recent_dumps)}** most recent brain dumps")
+            st.divider()
+            
+            for dump_id, text, cluster_id, created_at in recent_dumps:
+                render_feed_card(dump_id, text, cluster_id, cluster_labels_map)
+                st.markdown("")  # Spacing between cards
+
+
+# ============== MAIN APP ==============
+# Main content
+st.markdown("")  # Spacing
+
+# Get all dumps
+dumps = st.session_state.db.get_all_dumps()
+
+# Render selected tab
+if tab_selection == "Home":
+    render_home()
+else:
+    render_feed()
+
+# Footer
+st.divider()
+st.markdown("*Built with Google Gemini, Tavily Search, and Streamlit*")

braindump_core.py

@@ -0,0 +1,850 @@
+"""
+Brain Dump Sanctuary - Core Pipeline (Day 1 MVP + LangChain Integration)
+Now with Neo4j Graph Database Backend
+Runs entirely on CPU - no GPU needed
+"""
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+from sklearn.cluster import HDBSCAN
+import umap
+import plotly.graph_objects as go
+from datetime import datetime
+import json
+import os
+from dotenv import load_dotenv
+from neo4j import GraphDatabase
+from neo4j.exceptions import ServiceUnavailable, AuthError
+
+# Load environment variables from .env file
+load_dotenv()
+
+# LangChain imports for cluster labeling with Gemini
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnableWithFallbacks
+
+# ============== 1. DATABASE LAYER - Neo4j ==============
+class BrainDumpDB:
+    """
+    Neo4j-based graph database for Brain Dump Sanctuary.
+    
+    Graph Schema:
+    - Node: Dump {id, text, embedding[], cluster_id, created_at}
+    - Node: Cluster {id, label, description, created_at}
+    - Relationship: Dump -[:IN_CLUSTER]-> Cluster
+    - Relationship: Dump -[:SIMILAR_TO {weight}]-> Dump
+    """
+    
+    def __init__(self):
+        """Initialize Neo4j connection from environment variables."""
+        self.uri = os.getenv("NEO4J_URI", "neo4j://localhost:7687")
+        self.user = os.getenv("NEO4J_USER", "neo4j")
+        self.password = os.getenv("NEO4J_PASSWORD", "password")
+        
+        try:
+            self.driver = GraphDatabase.driver(self.uri, auth=(self.user, self.password))
+            self.driver.verify_connectivity()
+            print(f"✓ Connected to Neo4j at {self.uri}")
+        except (ServiceUnavailable, AuthError) as e:
+            print(f"✗ Failed to connect to Neo4j: {e}")
+            print("  Make sure NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD are set in .env")
+            raise
+        
+        self._init_schema()
+    
+    def _init_schema(self):
+        """Initialize graph schema with nodes and indexes."""
+        with self.driver.session() as session:
+            # Create Dump nodes with indexes
+            session.run("""
+                CREATE INDEX dump_id_index IF NOT EXISTS 
+                FOR (d:Dump) ON (d.id)
+            """)
+            session.run("""
+                CREATE INDEX dump_created_index IF NOT EXISTS 
+                FOR (d:Dump) ON (d.created_at)
+            """)
+            
+            # Create Cluster nodes with indexes
+            session.run("""
+                CREATE INDEX cluster_id_index IF NOT EXISTS 
+                FOR (c:Cluster) ON (c.id)
+            """)
+            
+            print("✓ Graph schema initialized")
+    
+    def check_duplicate(self, text):
+        """
+        Check if a dump with the same text already exists in the database.
+        Returns the dump_id if duplicate found, None otherwise.
+        """
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (d:Dump {text: $text})
+                RETURN d.id as dump_id
+                LIMIT 1
+            """, text=text)
+            row = result.single()
+            if row:
+                return row["dump_id"]
+            return None
+    
+    def add_dump(self, text):
+        """
+        Add a new brain dump to the database.
+        Returns (dump_id, is_duplicate) tuple.
+        If duplicate exists, returns (existing_dump_id, True).
+        If new dump created, returns (new_dump_id, False).
+        """
+        # Check for duplicate first
+        existing_id = self.check_duplicate(text)
+        if existing_id:
+            return (existing_id, True)
+        
+        # No duplicate, create new dump
+        with self.driver.session() as session:
+            result = session.run("""
+                CREATE (d:Dump {
+                    id: randomUuid(),
+                    text: $text,
+                    created_at: datetime()
+                })
+                RETURN d.id as dump_id
+            """, text=text)
+            dump_id = result.single()["dump_id"]
+            return (dump_id, False)
+    
+    def get_all_dumps(self):
+        """Get all dumps with their cluster assignments and timestamps."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (d:Dump)
+                OPTIONAL MATCH (d)-[:IN_CLUSTER]->(c:Cluster)
+                RETURN d.id as id, d.text as text, c.id as cluster_id, d.created_at as created_at
+                ORDER BY d.created_at DESC
+            """)
+            return [(row["id"], row["text"], row["cluster_id"], row["created_at"]) for row in result]
+    
+    def update_embedding(self, dump_id, embedding):
+        """Store embedding vector for a dump."""
+        # Convert numpy array to list for Neo4j storage
+        embedding_list = embedding.astype(np.float32).tolist()
+        
+        with self.driver.session() as session:
+            session.run("""
+                MATCH (d:Dump {id: $dump_id})
+                SET d.embedding = $embedding
+            """, dump_id=dump_id, embedding=embedding_list)
+    
+    def update_cluster(self, dump_id, cluster_id):
+        """Assign dump to a cluster."""
+        with self.driver.session() as session:
+            # Remove existing cluster relationship
+            session.run("""
+                MATCH (d:Dump {id: $dump_id})-[r:IN_CLUSTER]->()
+                DELETE r
+            """, dump_id=dump_id)
+            
+            # Create or match cluster node and add relationship
+            session.run("""
+                MATCH (d:Dump {id: $dump_id})
+                MERGE (c:Cluster {id: $cluster_id})
+                ON CREATE SET c.created_at = datetime()
+                CREATE (d)-[:IN_CLUSTER]->(c)
+            """, dump_id=dump_id, cluster_id=int(cluster_id))
+    
+    def get_embeddings(self):
+        """Retrieve all embeddings from database."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (d:Dump)
+                WHERE d.embedding IS NOT NULL
+                RETURN d.id as dump_id, d.embedding as embedding
+            """)
+            embeddings = []
+            for row in result:
+                dump_id = row["dump_id"]
+                embedding_list = row["embedding"]
+                # Convert list back to numpy array
+                embedding = np.array(embedding_list, dtype=np.float32)
+                embeddings.append((dump_id, embedding))
+            return embeddings
+    
+    def save_cluster_label(self, cluster_id, label, description=None):
+        """Save or update a cluster label."""
+        with self.driver.session() as session:
+            session.run("""
+                MERGE (c:Cluster {id: $cluster_id})
+                ON CREATE SET c.created_at = datetime()
+                SET c.label = $label, c.description = $description
+            """, cluster_id=int(cluster_id), label=label, description=description)
+    
+    def get_cluster_label(self, cluster_id):
+        """Get label for a specific cluster."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (c:Cluster {id: $cluster_id})
+                RETURN c.label as label, c.description as description
+            """, cluster_id=int(cluster_id))
+            row = result.single()
+            if row:
+                return (row["label"], row["description"])
+            return (None, None)
+    
+    def get_all_cluster_labels(self):
+        """Get all cluster labels."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (c:Cluster)
+                RETURN c.id as cluster_id, c.label as label, c.description as description
+            """)
+            return {
+                row["cluster_id"]: {
+                    "label": row["label"],
+                    "description": row["description"]
+                }
+                for row in result
+            }
+    
+    def get_cluster_dumps(self, cluster_id):
+        """Get all dumps in a specific cluster."""
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (d:Dump)-[:IN_CLUSTER]->(c:Cluster {id: $cluster_id})
+                RETURN d.id as dump_id, d.text as text
+            """, cluster_id=int(cluster_id))
+            return [(row["dump_id"], row["text"]) for row in result]
+    
+    def add_generated_dump(self, text, cluster_id):
+        """
+        Add a generated braindump directly to a specific cluster.
+        Returns (dump_id, is_duplicate) tuple.
+        If duplicate exists, returns (existing_dump_id, True) without adding to cluster.
+        If new dump created, returns (new_dump_id, False).
+        """
+        # Check for duplicate first
+        existing_id = self.check_duplicate(text)
+        if existing_id:
+            return (existing_id, True)
+        
+        # No duplicate, create new dump and assign to cluster
+        with self.driver.session() as session:
+            result = session.run("""
+                CREATE (d:Dump {
+                    id: randomUuid(),
+                    text: $text,
+                    created_at: datetime()
+                })
+                WITH d
+                MATCH (c:Cluster {id: $cluster_id})
+                CREATE (d)-[:IN_CLUSTER]->(c)
+                RETURN d.id as dump_id
+            """, text=text, cluster_id=int(cluster_id))
+            dump_id = result.single()["dump_id"]
+            return (dump_id, False)
+    
+    def save_feed_cache(self, dump_id, summary, questions, image_urls=None):
+        """
+        Store cached feed data (summary, questions, and image URLs) for a dump.
+        
+        Args:
+            dump_id: ID of the dump
+            summary: Summary text from FeedAgent
+            questions: List of reflection questions
+            image_urls: List of image URLs related to the brain dump
+        """
+        with self.driver.session() as session:
+            # Store as JSON strings for Neo4j compatibility
+            questions_json = json.dumps(questions) if isinstance(questions, list) else questions
+            image_urls_json = json.dumps(image_urls) if image_urls else json.dumps([])
+            
+            session.run("""
+                MATCH (d:Dump {id: $dump_id})
+                SET d.summary = $summary,
+                    d.questions = $questions,
+                    d.image_urls = $image_urls,
+                    d.feed_cache_generated_at = datetime()
+            """, dump_id=dump_id, summary=summary, questions=questions_json, image_urls=image_urls_json)
+    
+    def get_feed_cache(self, dump_id):
+        """
+        Retrieve cached feed data for a dump.
+        Returns: {"summary": str, "questions": list, "image_urls": list} or None if not cached
+        """
+        with self.driver.session() as session:
+            result = session.run("""
+                MATCH (d:Dump {id: $dump_id})
+                RETURN d.summary as summary, d.questions as questions, d.image_urls as image_urls
+            """, dump_id=dump_id)
+            
+            row = result.single()
+            if row and row["summary"]:
+                questions = json.loads(row["questions"]) if row["questions"] else []
+                image_urls = json.loads(row["image_urls"]) if row["image_urls"] else []
+                return {
+                    "summary": row["summary"],
+                    "questions": questions,
+                    "image_urls": image_urls
+                }
+            return None
+    
+    def close(self):
+        """Close database connection."""
+        self.driver.close()
+
+
+# ============== 2. EMBEDDING ENGINE ==============
+class EmbeddingEngine:
+    def __init__(self, model_name='all-MiniLM-L6-v2'):
+        print(f"Loading embedding model: {model_name}")
+        self.model = SentenceTransformer(model_name)
+        print("✓ Model loaded (CPU mode)")
+    
+    def embed(self, texts):
+        """Fast CPU inference - 5-10ms per text"""
+        if isinstance(texts, str):
+            texts = [texts]
+        embeddings = self.model.encode(texts, show_progress_bar=True)
+        return embeddings
+
+
+# ============== 3. CLUSTERING ENGINE ==============
+class ClusterEngine:
+    def __init__(self, min_cluster_size=3):
+        self.min_cluster_size = min_cluster_size
+        self.clusterer = None
+        self.reducer = None
+        self.llm = None
+        self.labeling_chain = None
+        
+        # Initialize LangChain for cluster labeling
+        self._init_labeling_chain()
+    
+    def _init_labeling_chain(self):
+        """Initialize LangChain chain for automatic cluster labeling with Google Gemini"""
+        try:
+            api_key = os.environ.get("GOOGLE_API_KEY")
+            if not api_key:
+                print("⚠️ GOOGLE_API_KEY not found. Cluster labeling will be disabled.")
+                print("   Get your API key from: https://aistudio.google.com/app/apikey")
+                return
+            
+            # Create primary Gemini LLM
+            primary_llm = ChatGoogleGenerativeAI(
+                model="gemini-2.5-flash",
+                temperature=0.3,
+                google_api_key=api_key
+            )
+            
+            # Create fallback Gemini LLM (using same model but could use gemini-pro)
+            fallback_llm = ChatGoogleGenerativeAI(
+                model="gemini-2.5-flash",
+                temperature=0.5,
+                google_api_key=api_key
+            )
+            
+            # LLM with fallback support
+            self.llm = primary_llm.with_fallbacks([fallback_llm])
+            
+            # Create labeling prompt
+            prompt = ChatPromptTemplate.from_template(
+                """You are an expert at identifying themes in clusters of related thoughts.
+
+Given these brain dump entries from a cluster:
+{cluster_texts}
+
+Task: Generate a short, descriptive label (2-4 words) that captures the unifying theme.
+
+Rules:
+- Be specific and insightful
+- Use natural language, not generic terms
+- Focus on the underlying curiosity or topic
+- Be specific if entries are less.
+- Be broad if entries are more.
+
+Label:"""
+            )
+            
+            # Create the chain
+            self.labeling_chain = (
+                prompt 
+                | self.llm 
+                | StrOutputParser()
+            )
+            
+            print("✓ LangChain cluster labeling initialized with Google Gemini")
+            
+        except Exception as e:
+            print(f"⚠️ Could not initialize cluster labeling: {e}")
+            self.llm = None
+            self.labeling_chain = None
+    
+    def generate_cluster_label(self, cluster_texts):
+        """Generate a label for a cluster using LangChain"""
+        if not self.labeling_chain:
+            return "Cluster"
+        
+        try:
+            # Take up to 5 representative texts
+            sample_texts = cluster_texts[:5]
+            texts_str = "\n".join([f"- {text}" for text in sample_texts])
+            
+            label = self.labeling_chain.invoke({"cluster_texts": texts_str})
+            return label.strip()
+            
+        except Exception as e:
+            print(f"⚠️ Cluster labeling failed: {e}")
+            return "Cluster"
+    
+    def fit_predict(self, embeddings):
+        """HDBSCAN clustering - works great on CPU"""
+        print(f"Clustering {len(embeddings)} brain dumps...")
+        
+        n_samples = len(embeddings)
+        
+        # Adjust min_cluster_size for small datasets
+        effective_min_cluster_size = min(self.min_cluster_size, max(2, n_samples // 2))
+        
+        # HDBSCAN for semantic clustering
+        self.clusterer = HDBSCAN(
+            min_cluster_size=effective_min_cluster_size,
+            metric='euclidean',
+            cluster_selection_method='eom',
+            min_samples=1  # More lenient clustering
+        )
+        clusters = self.clusterer.fit_predict(embeddings)
+        
+        # UMAP for 2D visualization with better separation parameters
+        # n_neighbors controls local vs global structure (lower = tighter clusters)
+        n_neighbors = max(2, min(10, n_samples - 1))  # Reduced from 15 for tighter clusters
+        
+        # For very small datasets, use simpler initialization
+        init = 'spectral' if n_samples > 10 else 'random'
+        
+        self.reducer = umap.UMAP(
+            n_components=2,
+            random_state=42,
+            n_neighbors=n_neighbors,
+            min_dist=0.3,  # Increased from 0.1 for better separation between clusters
+            spread=1.5,     # Controls how clumped embeddings are (higher = more spread)
+            metric='euclidean',
+            init=init,
+            negative_sample_rate=10,  # Helps with separation
+            repulsion_strength=1.2    # Pushes dissimilar points apart
+        )
+        coords_2d = self.reducer.fit_transform(embeddings)
+        
+        print(f"✓ Found {len(set(clusters)) - (1 if -1 in clusters else 0)} clusters")
+        return clusters, coords_2d
+
+
+# ============== 4. VISUALIZATION ==============
+def build_graph_edges(embeddings, clusters, max_edges_per_node=5, similarity_threshold=0.7):
+    """Build edges between semantically similar items (Obsidian knowledge graph style)"""
+    from sklearn.metrics.pairwise import cosine_similarity
+    
+    edges = []
+    similarities = cosine_similarity(embeddings)
+    
+    # Add edges between items in same cluster
+    unique_clusters = set(clusters)
+    for cluster_id in unique_clusters:
+        if cluster_id == -1:  # Skip noise
+            continue
+        
+        cluster_indices = np.where(clusters == cluster_id)[0]
+        
+        # Connect items within cluster (up to max_edges_per_node each)
+        for i in cluster_indices:
+            # Find most similar items in same cluster
+            cluster_similarities = [
+                (j, similarities[i][j]) for j in cluster_indices if i != j
+            ]
+            cluster_similarities.sort(key=lambda x: x[1], reverse=True)
+            
+            for j, sim in cluster_similarities[:max_edges_per_node]:
+                if i < j:  # Avoid duplicates
+                    edges.append((i, j, sim))
+    
+    return edges
+
+
+def create_knowledge_graph(dump_data, coords_2d, clusters, cluster_labels=None, embeddings=None):
+    """
+    Obsidian-style knowledge graph visualization with force-directed layout.
+    Shows connections between related brain dumps in a network style.
+    """
+    
+    fig = go.Figure()
+    
+    # Color palette for clusters
+    cluster_colors = [
+        '#FF6B6B',  # Red
+        '#4ECDC4',  # Teal
+        '#45B7D1',  # Sky Blue
+        '#FFA07A',  # Light Salmon
+        '#98D8C8',  # Mint
+        '#F7DC6F',  # Yellow
+        '#BB8FCE',  # Purple
+        '#85C1E2',  # Light Blue
+        '#F8B739',  # Orange
+        '#52BE80',  # Green
+        '#EC7063',  # Coral
+        '#AF7AC5',  # Lavender
+        '#5DADE2',  # Ocean Blue
+        '#48C9B0',  # Turquoise
+        '#F1948A',  # Pink
+        '#85929E',  # Gray Blue
+        '#F39C12',  # Dark Orange
+        '#3498DB',  # Bright Blue
+        '#E74C3C',  # Bright Red
+        '#9B59B6'   # Violet
+    ]
+    
+    # Color map for clusters
+    unique_clusters = set(clusters)
+    colors = {-1: '#95A5A6'}  # Gray for noise points
+    
+    for i, c in enumerate([c for c in unique_clusters if c != -1]):
+        colors[c] = cluster_colors[i % len(cluster_colors)]
+    
+    # Build edges between related items
+    edges = []
+    if embeddings is not None:
+        edges = build_graph_edges(embeddings, clusters)
+    
+    # Draw edges first (so they appear behind nodes)
+    for i, j, similarity in edges:
+        x0, y0 = coords_2d[i]
+        x1, y1 = coords_2d[j]
+        
+        # Edge opacity based on similarity
+        edge_opacity = 0.2 + (similarity - 0.7) * 0.4  # Range: 0.2-0.6
+        edge_opacity = max(0.1, min(0.6, edge_opacity))
+        
+        fig.add_trace(go.Scatter(
+            x=[x0, x1, None],
+            y=[y0, y1, None],
+            mode='lines',
+            line=dict(
+                width=1.5,
+                color=f'rgba(200, 200, 200, {edge_opacity})',
+            ),
+            hoverinfo='none',
+            showlegend=False,
+            name='',
+        ))
+    
+    # Draw nodes (clusters)
+    for cluster_id in unique_clusters:
+        mask = clusters == cluster_id
+        cluster_coords = coords_2d[mask]
+        cluster_texts = [dump_data[i][1] for i in range(len(dump_data)) if clusters[i] == cluster_id]
+        
+        # Get cluster label if available
+        if cluster_labels and cluster_id in cluster_labels:
+            label = cluster_labels[cluster_id]
+        else:
+            label = f"Cluster {cluster_id}" if cluster_id != -1 else "Unclustered"
+        
+        # Determine node size (larger for bigger clusters)
+        node_size = min(24, 14 + len(cluster_texts) // 2)
+        
+        fig.add_trace(go.Scatter(
+            x=cluster_coords[:, 0],
+            y=cluster_coords[:, 1],
+            mode='markers',
+            name=label,
+            marker=dict(
+                size=node_size,
+                color=colors[cluster_id],
+                line=dict(width=2, color='rgba(255, 255, 255, 0.8)'),
+                opacity=0.95,
+                symbol='circle',
+            ),
+            text=cluster_texts,
+            hovertext=[f"<b>{text}</b>" for text in cluster_texts],
+            hoverinfo='text',
+            showlegend=True,
+        ))
+    
+    fig.update_layout(
+        title={
+            'text': "🧠 Brain Dump Sanctuary - Knowledge Graph",
+            'x': 0.5,
+            'xanchor': 'center',
+            'font': {'size': 20, 'color': 'white'}
+        },
+        showlegend=True,
+        hovermode='closest',
+        width=1400,
+        height=800,
+        plot_bgcolor='#0d1117',
+        paper_bgcolor='#0d1117',
+        font=dict(color='white', family='monospace'),
+        xaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showticklabels=False,
+            showline=False,
+        ),
+        yaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showticklabels=False,
+            showline=False,
+        ),
+        margin=dict(l=0, r=200, t=50, b=0),
+        legend=dict(
+            orientation="v",
+            yanchor="top",
+            y=0.99,
+            xanchor="left",
+            x=1.02,
+            bgcolor='rgba(13, 17, 23, 0.9)',
+            bordercolor='#30363d',
+            borderwidth=1,
+            font=dict(size=11),
+        ),
+    )
+    
+    return fig
+
+
+def create_cluster_graph(dump_data, coords_2d, clusters, cluster_labels=None):
+    """Interactive Plotly visualization with cluster labels (Legacy - use create_knowledge_graph instead)"""
+    
+    fig = go.Figure()
+    
+    # Expanded color palette with 20 distinct colors
+    cluster_colors = [
+        '#FF6B6B',  # Red
+        '#4ECDC4',  # Teal
+        '#45B7D1',  # Sky Blue
+        '#FFA07A',  # Light Salmon
+        '#98D8C8',  # Mint
+        '#F7DC6F',  # Yellow
+        '#BB8FCE',  # Purple
+        '#85C1E2',  # Light Blue
+        '#F8B739',  # Orange
+        '#52BE80',  # Green
+        '#EC7063',  # Coral
+        '#AF7AC5',  # Lavender
+        '#5DADE2',  # Ocean Blue
+        '#48C9B0',  # Turquoise
+        '#F1948A',  # Pink
+        '#85929E',  # Gray Blue
+        '#F39C12',  # Dark Orange
+        '#3498DB',  # Bright Blue
+        '#E74C3C',  # Bright Red
+        '#9B59B6'   # Violet
+    ]
+    
+    # Color map for clusters
+    unique_clusters = set(clusters)
+    colors = {-1: '#95A5A6'}  # Gray for noise points
+    
+    for i, c in enumerate([c for c in unique_clusters if c != -1]):
+        colors[c] = cluster_colors[i % len(cluster_colors)]
+    
+    # Plot each cluster
+    for cluster_id in unique_clusters:
+        mask = clusters == cluster_id
+        cluster_coords = coords_2d[mask]
+        cluster_texts = [dump_data[i][1] for i in range(len(dump_data)) if clusters[i] == cluster_id]
+        
+        # Get cluster label if available
+        if cluster_labels and cluster_id in cluster_labels:
+            label = cluster_labels[cluster_id]
+        else:
+            label = f"Cluster {cluster_id}" if cluster_id != -1 else "Unclustered"
+        
+        fig.add_trace(go.Scatter(
+            x=cluster_coords[:, 0],
+            y=cluster_coords[:, 1],
+            mode='markers+text',
+            name=label,
+            marker=dict(
+                size=14,  # Slightly larger for visibility
+                color=colors[cluster_id],
+                line=dict(width=2, color='white'),  # Thicker white border
+                opacity=0.9  # Slight transparency to see overlaps
+            ),
+            text=[f"{i+1}" for i in range(len(cluster_texts))],
+            textposition="top center",
+            textfont=dict(size=10, color='white'),
+            hovertext=cluster_texts,
+            hoverinfo='text'
+        ))
+    
+    fig.update_layout(
+        title="Brain Dump Sanctuary - Semantic Clusters",
+        showlegend=True,
+        hovermode='closest',
+        width=1200,  # Wider for better separation
+        height=700,  # Taller for better separation
+        plot_bgcolor='#1a1a1a',  # Dark background
+        paper_bgcolor='#0d1117',
+        font=dict(color='white'),
+        xaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+        yaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+        legend=dict(
+            orientation="v",
+            yanchor="top",
+            y=1,
+            xanchor="left",
+            x=1.02,
+            bgcolor='rgba(13, 17, 23, 0.8)',
+            bordercolor='#30363d',
+            borderwidth=1
+        )
+    )
+    
+    return fig
+
+
+# ============== 5. DEMO PIPELINE ==============
+def run_demo():
+    """Complete pipeline demo"""
+    
+    # Sample brain dumps
+    sample_dumps = [
+        # Consciousness & Mind (8 items)
+        "Why do dreams feel so real but fade so quickly?",
+        "Is consciousness an emergent property?",
+        "Why do we forget things we just read?",
+        "What causes earworms (songs stuck in head)?",
+        "Why does time feel faster as we age?",
+        "How does anesthesia actually work?",
+        "What makes us self-aware?",
+        "Can machines ever truly be conscious?",
+        
+        # Physics & Quantum (8 items)
+        "How does quantum entanglement actually work?",
+        "Is math discovered or invented?",
+        "What happens at the event horizon of a black hole?",
+        "Why is the speed of light constant?",
+        "What is dark matter made of?",
+        "How can particles be in two places at once?",
+        "What came before the Big Bang?",
+        "Why does time only move forward?",
+        
+        # AI & Technology (8 items)
+        "Are LLMs actually understanding or just pattern matching?",
+        "How do neural networks learn representations?",
+        "What makes a question 'good' vs 'bad'?",
+        "Can AI ever be truly creative?",
+        "How do transformers attend to context?",
+        "What is the halting problem and why does it matter?",
+        "Will we ever achieve AGI?",
+        "How do computers generate random numbers?",
+        
+        # Biology & Nature (8 items)
+        "How do birds navigate during migration?",
+        "What causes the smell of rain on dry ground?",
+        "What's the connection between gut bacteria and mood?",
+        "How do whales communicate across oceans?",
+        "Why do cats purr?",
+        "How do fireflies synchronize their flashing?",
+        "Why do we yawn when others yawn?",
+        "How do octopuses change color instantly?",
+        
+        # Food & Chemistry (8 items)
+        "What makes sourdough bread different from regular bread?",
+        "Why does coffee smell better than it tastes?",
+        "What makes food spicy and why do we like it?",
+        "How does fermentation preserve food?",
+        "Why does chocolate melt at body temperature?",
+        "What causes that metallic taste when you bite foil?",
+        "Why do onions make us cry?",
+        "How do flavors combine to create umami?",
+        
+        # Music & Art (8 items)
+        "Why do some songs give me chills?",
+        "What makes a melody memorable?",
+        "How does rhythm affect our emotions?",
+        "Why do major keys sound happy and minor keys sad?",
+        "What makes abstract art 'good'?",
+        "How does color theory influence mood?",
+        "Why do we find symmetry beautiful?",
+        "What is the golden ratio in design?",
+        
+        # Psychology & Society (8 items)
+        "Why do we procrastinate even when we know better?",
+        "How does confirmation bias shape our beliefs?",
+        "What causes impostor syndrome?",
+        "Why are first impressions so lasting?",
+        "How do echo chambers form online?",
+        "What makes some ideas go viral?",
+        "Why is it hard to change someone's mind?",
+        "How does groupthink override individual judgment?",
+        
+        # Language & Communication (4 items)
+        "Why do different languages have different sounds?",
+        "How did writing systems evolve independently?",
+        "What makes a joke funny across cultures?",
+        "Why do babies learn language so easily?"
+    ]
+    
+    print("=== BRAIN DUMP SANCTUARY - DEMO ===\n")
+    
+    # 1. Initialize
+    db = BrainDumpDB()
+    embedder = EmbeddingEngine()
+    clusterer = ClusterEngine(min_cluster_size=2)
+    
+    # 2. Add dumps to database
+    print("\n[1/4] Adding brain dumps to database...")
+    for dump in sample_dumps:
+        dump_id, is_duplicate = db.add_dump(dump)
+        if is_duplicate:
+            print(f"  Skipped duplicate: {dump[:50]}...")
+    
+    # 3. Generate embeddings
+    print("\n[2/4] Generating embeddings (CPU)...")
+    dumps = db.get_all_dumps()
+    texts = [d[1] for d in dumps]
+    embeddings = embedder.embed(texts)
+    
+    for i, (dump_id, text, _, created_at) in enumerate(dumps):
+        db.update_embedding(dump_id, embeddings[i])
+    
+    # 4. Cluster
+    print("\n[3/5] Performing semantic clustering...")
+    clusters, coords_2d = clusterer.fit_predict(embeddings)
+    
+    for i, (dump_id, _, _, _) in enumerate(dumps):
+        db.update_cluster(dump_id, clusters[i])
+    
+    # 5. Auto-generate cluster labels using LangChain
+    print("\n[4/5] Generating cluster labels with LLM...")
+    cluster_labels = {}
+    unique_clusters = set(clusters) - {-1}
+    
+    for cluster_id in unique_clusters:
+        cluster_dumps = [dumps[i][1] for i in range(len(dumps)) if clusters[i] == cluster_id]
+        label = clusterer.generate_cluster_label(cluster_dumps)
+        cluster_labels[cluster_id] = label
+        db.save_cluster_label(cluster_id, label)
+        print(f"  Cluster {cluster_id}: '{label}'")
+    
+    # 6. Visualize
+    print("\n[5/5] Creating knowledge graph visualization...")
+    fig = create_knowledge_graph(dumps, coords_2d, clusters, cluster_labels, embeddings)
+    fig.write_html("brain_dump_knowledge_graph.html")
+    print("✓ Saved to: brain_dump_knowledge_graph.html")
+    
+    # 7. Show cluster insights
+    print("\n=== CLUSTER INSIGHTS ===")
+    for cluster_id in sorted(unique_clusters):
+        cluster_dumps = [dumps[i][1] for i in range(len(dumps)) if clusters[i] == cluster_id]
+        label = cluster_labels.get(cluster_id, f"Cluster {cluster_id}")
+        print(f"\n{label} ({len(cluster_dumps)} items):")
+        for dump in cluster_dumps[:3]:  # Show first 3
+            print(f"  - {dump}")
+
+
+if __name__ == "__main__":
+    run_demo()

neo4j_maintenance.py

@@ -0,0 +1,102 @@
+"""
+Neo4j Database Maintenance Script
+Use this to manage your Brain Dump Sanctuary Neo4j database
+"""
+
+import os
+from dotenv import load_dotenv
+from braindump_core import BrainDumpDB
+
+load_dotenv()
+
+def clear_all_dumps():
+    """Clear all dumps from the database."""
+    db = BrainDumpDB()
+    with db.driver.session() as session:
+        # Delete all relationships and nodes
+        session.run("MATCH (d:Dump) DETACH DELETE d")
+        session.run("MATCH (c:Cluster) DETACH DELETE c")
+    print("✓ All dumps and clusters cleared from Neo4j")
+    db.close()
+
+def show_database_stats():
+    """Show current database statistics."""
+    db = BrainDumpDB()
+    with db.driver.session() as session:
+        # Count dumps
+        result_dumps = session.run("MATCH (d:Dump) RETURN COUNT(d) as count")
+        dump_count = result_dumps.single()["count"]
+        
+        # Count clusters
+        result_clusters = session.run("MATCH (c:Cluster) RETURN COUNT(c) as count")
+        cluster_count = result_clusters.single()["count"]
+        
+        # Count relationships
+        result_rels = session.run("MATCH ()-[r:IN_CLUSTER]->() RETURN COUNT(r) as count")
+        rel_count = result_rels.single()["count"]
+    
+    print("\n=== Neo4j Database Statistics ===")
+    print(f"Total Brain Dumps: {dump_count}")
+    print(f"Total Clusters: {cluster_count}")
+    print(f"Dump-to-Cluster Relationships: {rel_count}")
+    
+    db.close()
+
+def remove_duplicates():
+    """Remove duplicate brain dumps (same text)."""
+    db = BrainDumpDB()
+    with db.driver.session() as session:
+        # Find duplicates
+        result = session.run("""
+            MATCH (d:Dump)
+            WITH d.text as text, COLLECT(d.id) as ids
+            WHERE SIZE(ids) > 1
+            RETURN text, ids
+        """)
+        
+        duplicates = list(result)
+        if not duplicates:
+            print("✓ No duplicates found!")
+        else:
+            print(f"Found {len(duplicates)} duplicate texts:")
+            for row in duplicates:
+                text = row["text"]
+                ids = row["ids"]
+                print(f"  - '{text[:50]}...' appears {len(ids)} times")
+                
+                # Keep first, delete rest
+                for dup_id in ids[1:]:
+                    session.run("""
+                        MATCH (d:Dump {id: $dump_id})
+                        DETACH DELETE d
+                    """, dump_id=dup_id)
+            
+            print(f"✓ Removed duplicate entries")
+    
+    db.close()
+
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) < 2:
+        print("Usage: python neo4j_maintenance.py <command>")
+        print("\nCommands:")
+        print("  stats      - Show database statistics")
+        print("  clear      - Clear all dumps and clusters")
+        print("  dedup      - Remove duplicate brain dumps")
+        sys.exit(1)
+    
+    command = sys.argv[1]
+    
+    if command == "stats":
+        show_database_stats()
+    elif command == "clear":
+        confirm = input("Are you sure? This will delete all data. (yes/no): ")
+        if confirm.lower() == "yes":
+            clear_all_dumps()
+        else:
+            print("Cancelled.")
+    elif command == "dedup":
+        remove_duplicates()
+    else:
+        print(f"Unknown command: {command}")

requirements.txt

@@ -1,3 +1,31 @@
-altair
-pandas
-streamlit
+# requirements.txt
+# Core ML/NLP
+sentence-transformers
+scikit-learn==1.3.2
+hdbscan==0.8.33
+umap-learn==0.5.5
+
+# LLM & Agents
+langgraph==0.2.0
+langchain==0.2.0
+langchain-google-genai
+
+# Web Search
+tavily-python
+fuzzywuzzy[speedup]
+requests
+
+# Database - Graph DB (Neo4j)
+neo4j==5.17.0
+
+# Visualization & UI
+streamlit==1.51.0
+plotly==5.18.0
+
+# Data
+pandas==2.1.3
+numpy==1.24.3
+pytz
+
+# Environment
+python-dotenv

src/streamlit_app.py

@@ -1,40 +0,0 @@
-import altair as alt
-import numpy as np
-import pandas as pd
-import streamlit as st
-
-"""
-# Welcome to Streamlit!
-
-Edit `/streamlit_app.py` to customize this app to your heart's desire :heart:.
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
-
-In the meantime, below is an example of what you can do with just a few lines of code:
-"""
-
-num_points = st.slider("Number of points in spiral", 1, 10000, 1100)
-num_turns = st.slider("Number of turns in spiral", 1, 300, 31)
-
-indices = np.linspace(0, 1, num_points)
-theta = 2 * np.pi * num_turns * indices
-radius = indices
-
-x = radius * np.cos(theta)
-y = radius * np.sin(theta)
-
-df = pd.DataFrame({
-    "x": x,
-    "y": y,
-    "idx": indices,
-    "rand": np.random.randn(num_points),
-})
-
-st.altair_chart(alt.Chart(df, height=700, width=700)
-    .mark_point(filled=True)
-    .encode(
-        x=alt.X("x", axis=None),
-        y=alt.Y("y", axis=None),
-        color=alt.Color("idx", legend=None, scale=alt.Scale()),
-        size=alt.Size("rand", legend=None, scale=alt.Scale(range=[1, 150])),
-    ))

test_duplicate_detection.py

@@ -0,0 +1,59 @@
+"""
+Test script to verify duplicate detection functionality
+"""
+
+from braindump_core import BrainDumpDB
+
+def test_duplicate_detection():
+    """Test that duplicate brain dumps are detected and not re-added"""
+    
+    print("=== Testing Duplicate Detection ===\n")
+    
+    # Initialize database
+    db = BrainDumpDB()
+    
+    # Test 1: Add a new dump
+    test_text = "Why do dreams feel so real but fade so quickly?"
+    print(f"Test 1: Adding new dump...")
+    dump_id1, is_duplicate1 = db.add_dump(test_text)
+    print(f"  Result: dump_id={dump_id1}, is_duplicate={is_duplicate1}")
+    assert not is_duplicate1, "First addition should not be a duplicate"
+    print("  ✓ PASS: New dump added successfully\n")
+    
+    # Test 2: Try to add the same dump again
+    print(f"Test 2: Adding same dump again...")
+    dump_id2, is_duplicate2 = db.add_dump(test_text)
+    print(f"  Result: dump_id={dump_id2}, is_duplicate={is_duplicate2}")
+    assert is_duplicate2, "Second addition should be detected as duplicate"
+    assert dump_id1 == dump_id2, "Should return the same dump_id"
+    print("  ✓ PASS: Duplicate detected and prevented\n")
+    
+    # Test 3: Add a different dump
+    different_text = "How does quantum entanglement actually work?"
+    print(f"Test 3: Adding different dump...")
+    dump_id3, is_duplicate3 = db.add_dump(different_text)
+    print(f"  Result: dump_id={dump_id3}, is_duplicate={is_duplicate3}")
+    assert not is_duplicate3, "Different dump should not be a duplicate"
+    assert dump_id3 != dump_id1, "Should have a different dump_id"
+    print("  ✓ PASS: Different dump added successfully\n")
+    
+    # Test 4: Verify total count
+    all_dumps = db.get_all_dumps()
+    print(f"Test 4: Verifying database state...")
+    print(f"  Total dumps in database: {len(all_dumps)}")
+    print(f"  Expected at least 2 unique dumps")
+    # Note: We might have more dumps from previous runs
+    print("  ✓ Database contains the dumps\n")
+    
+    # Clean up
+    db.close()
+    
+    print("=== All Tests Passed! ===")
+    print("\nDuplicate detection is working correctly:")
+    print("  ✓ New dumps are added")
+    print("  ✓ Duplicate dumps are detected")
+    print("  ✓ Duplicate dumps return existing ID")
+    print("  ✓ Different dumps are treated separately")
+
+if __name__ == "__main__":
+    test_duplicate_detection()