Update README.md

README.md

@@ -1,6 +1,7 @@
 ---
-title: ReMind
-emoji: 🧠
+
+title: ReMind — Your Second 🧠
+emoji: "🧠"
 colorFrom: blue
 colorTo: purple
 sdk: gradio
@@ -15,109 +16,158 @@ tags:
 - bookmarks
 - web-search
 - agent-demo-track
+
 ---
 
-# 🧠 ReMind - Digital Assistant
+# 🧠 ReMind — Bring your past to mind
+
+**ReMind is a unified digital-memory assistant that learns from your AI newsletters, curates your Chrome bookmarks, and lets you query both in natural language—all orchestrated by a multi-agent system.**
 
-**Agents-MCP-Hackathon 2025 Submission - Track 3: Agentic Demo Showcase**
+Built for the **Agents & MCP Hackathon 2025 — Track 3: Agentic Demo Showcase**.
 
-A comprehensive digital assistant that combines Gmail management, Chrome bookmarks, and web search capabilities through an intelligent multi-agent system.
+> *"Email that teaches me, bookmarks that remember for me, answers when I need them."*
+
+---
+
+## ✨ Why ReMind?
+
+| Pain                                             | ReMind Solution                                         |
+| ------------------------------------------------ | ------------------------------------------------------- |
+| Newsletter overload every morning                | One-click OAuth fetch, auto-tagging & summarisation     |
+| Thousand-tab bookmark graveyard                  | AI categorisation & semantic search                     |
+| Context-switching between inbox, browser, search | Single chat interface powered by agents                 |
+| Opaque AI answers                                | Real-time “thought process” trace & clickable citations |
+
+---
 
-## ✨ Features
+## 🚀 Live Demo — 30-Second Flow
 
-- 🤖 **Multi-Agent Architecture**: Specialized agents for different tasks using SmolagentS
-- 📧 **Gmail Integration**: Read, search, and manage emails through Google API
-- 🔖 **Smart Bookmarks**: Parse and search Chrome bookmarks with AI categorization
-- 🌐 **Web Search**: Real-time web search capabilities with intelligent responses
-- 💭 **Real-time Thinking**: Watch the AI think through problems step-by-step
-- 🎯 **AI Categorization**: Intelligent categorization of content and information
+1. **Open the Space** and switch to **Tab 1 — Connect**.
+2. Click **“Connect Gmail”**, grant read-only access, then hit **“Ingest”**.
+3. Jump to **Tab 2 — Analytics** to see tag clouds and sender stats.
+4. Ask questions in **Tab 3 — Ask ReMind** e.g. “Summarise recent Anthropic updates.”
+5. Watch the agents think, then follow the citations back to the original email or bookmark.
 
-## 🎯 Hackathon Track
+[▶︎ **4-min video demo**](https://youtu.be/xxxxxxxx)
 
-This submission is for **Track 3: Agentic Demo Showcase** - demonstrating the power of AI agents in a practical, user-friendly application.
+---
 
-## 🛠️ Technology Stack
+## 🏗️ Repo Layout (monorepo-style)
 
-- **Gradio 5.0**: Modern web interface
-- **SmolagentS**: Multi-agent framework for AI coordination
-- **Google APIs**: Gmail integration
-- **Real-time Processing**: Live thinking display and response streaming
+```
+ReMind/
+├─ config/                # default prompts, yaml configs
+├─ data/                  # sample inbox & bookmark JSON (redacted)
+├─ src/                   # package root (importable as `remind`)
+│   ├─ agents/            # Manager, Gmail, Bookmark, RAG, etc.
+│   ├─ interfaces/        # Gradio Blocks & helper UI widgets
+│   ├─ tools/             # Gmail API wrapper, bookmark parser, utils
+│   ├─ __init__.py
+│   └─ main.py            # entrypoint when imported as a module
+├─ app.py                 # HF Spaces entrypoint (imports src.main)
+├─ .env.example           # copy → .env and fill in secrets
+├─ requirements.txt       # runtime deps
+├─ pyproject.toml         # tooling & formatting
+└─ README.md              # you are here
+```
 
-## 🚀 Key Capabilities
+The **root‐level `app.py`** is the single entrypoint required by Hugging Face Spaces. It bootstraps the Gradio UI by calling `remind.interfaces.build()` inside `src/`.
 
-### 📧 Email Management
-- Search through Gmail messages
-- Read and analyze email content
-- Smart email categorization and insights
+---
 
-### 🔖 Bookmarks Intelligence
-- Import and analyze Chrome bookmarks
-- AI-powered categorization
-- Smart search and recommendations
+## ⚙️ Quick Start (Local Dev)
 
-### 🌐 Web Search & Research
-- Real-time web search capabilities
-- Intelligent information synthesis
-- Context-aware responses
+```bash
+# 1. Clone & install
+$ git clone https://github.com/your-org/remind.git && cd remind
+$ pip install -r requirements.txt
 
-### 🤔 Transparent AI Thinking
-- Watch the AI's reasoning process in real-time
-- Understand how decisions are made
-- Educational insight into agent behavior
+# 2. Configure secrets
+$ cp .env.example .env  # then paste your tokens
 
-## 💡 Agent Architecture
+# 3. Launch the app
+$ python app.py         # opens http://localhost:7860
+```
 
-The system uses a sophisticated multi-agent approach:
+### Required Environment Variables
 
-1. **Manager Agent**: Orchestrates tasks and delegates to specialists
-2. **Gmail Agent**: Handles all email-related operations
-3. **Bookmarks Agent**: Manages bookmark analysis and search
-4. **Categorizer Agent**: Provides AI-powered categorization
-5. **Web Agents**: Handle search and real-time information retrieval
+| Key                                            | Description                                              |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| `HF_TOKEN`                                     | Hugging Face token for optional Inference API calls      |
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`    | OAuth credentials from Google Cloud Console              |
+| `GOOGLE_REFRESH_TOKEN` / `GOOGLE_ACCESS_TOKEN` | Generated by `python scripts/setup_gmail_credentials.py` |
 
-## 🎥 Demo Video
+> **Tip — Gmail setup**: Run `python scripts/setup_gmail_credentials.py` (included in `src/tools`) once. It opens a browser window, you sign in, and it prints the refresh & access tokens for `.env`.
 
-[Link to demo video showing ReMind in action]
+---
 
-## 🔧 Setup for Gmail Integration
+## 🛠️ Key Components
 
-To enable Gmail features, configure these environment variables in your Space:
+* **Multi-Agent Orchestrator** — built with *SmolagentS*; assigns Gmail parsing, bookmarking, and RAG tasks to specialists.
+* **LLM Stack** — OpenAI GPT-4o for reasoning, ADA-002 for embeddings (pluggable).
+* **Vector Store** — in-memory FAISS during hackathon (MongoDB Atlas planned).
+* **Gradio 5 UI** — three-tab layout + real-time agent “thoughts” accordion.
 
-```
-GOOGLE_CLIENT_ID=your_oauth_client_id
-GOOGLE_CLIENT_SECRET=your_oauth_client_secret  
-GOOGLE_REFRESH_TOKEN=your_refresh_token
-HF_TOKEN=your_hugging_face_token
-```
+---
 
-## 🏆 Hackathon Innovation
+## 🎯 Core Features (MVP)
 
-ReMind showcases several innovative aspects:
+1. **Gmail Ingestion (read-only)**
+   • Detect newsletters via `List-Unsubscribe` header
+   • Parse HTML → Markdown → clean text
+2. **Bookmark Brain**
+   • Import `Bookmarks.json`
+   • Zero-shot topic tagging
+3. **Natural-Language Q\&A**
+   • RAG over combined email+bookmark corpus
+   • Inline citations
+4. **Analytics Dashboard**
+   • Tag cloud, sender histogram, engagement insights
 
-- **Unified Interface**: Single chat interface for multiple productivity tools
-- **Transparent AI**: Real-time thinking display for educational value
-- **Practical Integration**: Real-world APIs (Gmail) with AI enhancement
-- **Smart Categorization**: AI-powered organization of digital content
-- **Multi-Agent Coordination**: Sophisticated task delegation and management
+---
+
+## 🛣️ Roadmap (Post-Hackathon)
+
+* Gmail push notifications for near real-time ingest
+* Atlas Vector Search backend
+* Shared team workspaces
+* Mobile PWA wrapper
+
+Contribute ideas → [Discussions](https://huggingface.co/spaces/Agents-MCP-Hackathon/ReMind/discussions).
+
+---
+
+## 🤝 Contributing
+
+PRs welcome! During hack-week we operate on a **fast-merge** basis.
+
+* README with live demo & video ✔️
+* HF Space public & reproducible ✔️
 
-## 🌟 User Experience
+If ReMind sparks joy, **⭐️ the repo & “Like” the Space** — community engagement counts!
 
-The interface provides:
-- Clean, intuitive chat interface
-- Real-time thinking visualization
-- Responsive design for all devices
-- Error handling and user guidance
-- Progressive feature discovery
+---
+
+## 👩‍💻 Authors
+
+| Name         | GitHub                                             | Role                                 |
+| ------------ | -------------------------------------------------- | ------------------------------------ |
+| Habib Adoum  | [@GhostDragon01](https://github.com/GhostDragon01) | Lead Full-Stack & Agent Orchestrator |
+| Omar Issa    | [@omarissa24](https://github.com/omarissa24)       | Contributor                          |
+| Ziad Mazzawi | [@zmazz](https://github.com/zmazz)                 | Contributor                          |
 
-## 📚 Use Cases
+Thanks to **Modal Labs**, **Hugging Face**, **OpenAI**, **MistralAI**, and **Anthropic** for credits that power this demo.
+
+---
+
+## 📄 License
+
+MIT — free to fork & learn. See `LICENSE`.
+
+---
 
-Perfect for users who want to:
-- Manage email more efficiently with AI assistance
-- Organize and search bookmarks intelligently
-- Get quick answers with web search integration
-- Learn how AI agents coordinate and think
-- Streamline daily digital productivity tasks
+> May your inbox be calm and your bookmarks memorable.
 
 ---
 
-*Built for the Agents-MCP-Hackathon 2025 by Habib*
+*Built for the Agents-MCP-Hackathon 2025 by Habib*