Update README.md

README.md

@@ -1,19 +1,230 @@
----
-title: Testing
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: Streamlit template space
----
+# 🕶️ Matrix AI Chat with RAG
+
+![Matrix AI Chat](https://img.shields.io/badge/Matrix-AI%20Chat-00ff00?style=for-the-badge&logo=matrix&logoColor=00ff00)
+![Python](https://img.shields.io/badge/Python-3.8+-blue?style=for-the-badge&logo=python)
+![Streamlit](https://img.shields.io/badge/Streamlit-FF4B4B?style=for-the-badge&logo=streamlit&logoColor=white)
+![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-yellow?style=for-the-badge)
+
+**Enter the Matrix** - An advanced AI chat interface with Retrieval-Augmented Generation (RAG) capabilities, featuring multiple AI models and a cyberpunk Matrix-themed UI.
+
+## 🚀 Live Demo
+
+Visit the live deployment: [Matrix AI Chat Space](https://huggingface.co/spaces/YOUR_USERNAME/matrix-ai-chat)
+
+## ✨ Features
+
+### 🤖 Multi-Model AI Support
+- **DeepSeek-R1**: Advanced reasoning model via Together AI
+- **Llama-3.2-3B**: Meta's efficient language model  
+- **Qwen2.5-VL-7B-Instruct**: Vision-language model via Hyperbolic
+
+### 🧠 Retrieval-Augmented Generation (RAG)
+- Upload and index custom documents
+- Semantic similarity search using sentence transformers
+- Context-aware responses based on your data
+- Persistent document storage with embeddings
+
+### 💾 Smart Memory System
+- Conversation history persistence
+- Session management with UUID tracking
+- Similarity-based response caching
+- Automatic context generation from chat history
+
+### 🎨 Matrix-Themed Interface
+- Cyberpunk green-on-black Matrix aesthetic
+- Glowing text effects and animations
+- Terminal-style fonts (Courier New)
+- Immersive digital realm experience
+
+### 🔧 Advanced Controls
+- Customizable system prompts
+- Session management (new sessions, data purging)
+- Real-time model status indicators
+- Comprehensive configuration panel
+
+## 🛠️ Setup & Installation
+
+### For Hugging Face Spaces Deployment
+
+1. **Fork or duplicate this Space**
+2. **Set your Hugging Face Token**:
+   - Go to Space Settings → Repository secrets
+   - Add `HF_TOKEN` with your Hugging Face API token
+   - Ensure your token has inference API access
+
+3. **Configure the Space**:
+   ```yaml
+   # In your Space's README.yml header
+   title: Matrix AI Chat with RAG
+   emoji: 🕶️
+   colorFrom: black
+   colorTo: green
+   sdk: streamlit
+   sdk_version: 1.28.0
+   app_file: app.py
+   pinned: false
+   license: mit
+   ```
+
+### For Local Development
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://huggingface.co/spaces/YOUR_USERNAME/matrix-ai-chat
+   cd matrix-ai-chat
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set environment variables**:
+   ```bash
+   export HF_TOKEN="your_hugging_face_token_here"
+   ```
+
+4. **Run the application**:
+   ```bash
+   streamlit run app.py
+   ```
+
+## 📋 Requirements
+
+Create a `requirements.txt` file with:
+
+```txt
+streamlit>=1.28.0
+numpy>=1.24.0
+sentence-transformers>=2.2.2
+scikit-learn>=1.3.0
+transformers>=4.30.0
+torch>=2.0.0
+huggingface-hub>=0.16.0
+openai>=1.0.0
+uuid
+```
+
+## 🎯 Usage Guide
+
+### Basic Chat
+1. Select your preferred AI model from the sidebar
+2. Enter your message in the chat input
+3. Watch as the Matrix processes your query with streaming effects
+
+### RAG Document Upload
+1. Open the "UPLOAD DATA" section in the sidebar
+2. Provide a title and content for your document
+3. Click "INJECT DATA" to add it to the knowledge base
+4. The system will automatically reference relevant documents in responses
 
-# Welcome to Streamlit!
+### Session Management
+- **NEW JACK IN**: Start a fresh conversation session
+- **PURGE ALL**: Clear all stored data (requires confirmation)
+- Sessions are automatically saved with persistent IDs
+
+### Advanced Configuration
+- Customize system prompts to change AI behavior
+- Monitor connection status for each model
+- View document count in your knowledge base
+
+## 🔑 API Keys & Tokens
+
+This application requires a **Hugging Face API Token** with inference access:
+
+1. Visit [Hugging Face Settings](https://huggingface.co/settings/tokens)
+2. Create a new token with "Inference API" permissions
+3. Add the token to your Space secrets or environment variables
+
+**Supported Providers:**
+- Together AI (via Hugging Face)
+- Hyperbolic (via Hugging Face Router)
+- Local Hugging Face models
+
+## 📁 Project Structure
+
+```
+matrix-ai-chat/
+├── app.py                 # Main Streamlit application
+├── requirements.txt       # Python dependencies
+├── README.md             # This file
+├── data/                 # Auto-created data directory
+│   ├── sessions/         # Chat session storage
+│   ├── documents/        # RAG document storage
+│   └── embeddings/       # Vector embeddings
+└── .gitignore           # Git ignore file
+```
+
+## 🚨 Important Notes
+
+### Data Persistence
+- All data is stored locally in the `data/` directory
+- Sessions, documents, and embeddings persist between app restarts
+- Use "PURGE ALL" to completely reset the system
+
+### Model Limitations
+- API-based models require active internet connection
+- Local models may have slower inference times
+- Token limits apply based on your Hugging Face plan
+
+### Security Considerations
+- Keep your HF_TOKEN secure and private
+- Documents uploaded are stored locally in the Space
+- Session data is tied to browser sessions
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"No Hugging Face token found"**
+- Ensure `HF_TOKEN` is set in your environment or Space secrets
+- Verify your token has inference API permissions
+
+**Model connection failed**
+- Check your internet connection
+- Verify your HF token is valid and has sufficient quota
+- Try switching to a different model
+
+**Embedding errors**
+- Ensure sufficient memory for sentence transformer models
+- Check if the embedding model downloaded successfully
+
+**Data not persisting**
+- Verify write permissions to the `data/` directory
+- Check available disk space
+
+## 🤝 Contributing
+
+1. Fork the Space or repository
+2. Create a feature branch
+3. Make your improvements
+4. Test thoroughly with different models
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Hugging Face** for the amazing model ecosystem and Spaces platform
+- **Streamlit** for the intuitive web app framework
+- **The Matrix** films for the visual inspiration
+- **SentenceTransformers** for semantic similarity capabilities
+- **Together AI** and **Hyperbolic** for API access
+
+## 🔮 Future Enhancements
+
+- [ ] Multi-modal support (image uploads)
+- [ ] Voice chat integration
+- [ ] Advanced RAG with document chunking
+- [ ] Real-time collaboration features
+- [ ] Custom model fine-tuning interface
+- [ ] Export/import chat sessions
+- [ ] Advanced analytics dashboard
+
+---
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+**Welcome to the Matrix. Red pill or blue pill? The choice is yours.** 🕶️
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+[![Deploy to Hugging Face Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/deploy-to-spaces-lg.svg)](https://huggingface.co/spaces/YOUR_USERNAME/matrix-ai-chat)