README.md

---
title: Matrix AI Chat with RAG
emoji: 🕶️
colorFrom: gray
colorTo: green
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false
license: mit
---

# 🕶️ Matrix AI Chat with RAG

**Enter the Matrix** - Advanced AI chat with Retrieval-Augmented Generation (RAG) and multiple AI models.

## ✨ Features

- **Multi-Model Support**: DeepSeek-R1, Llama-3.2-3B, Qwen2.5-VL-7B
- **RAG System**: Upload documents for context-aware responses
- **Matrix UI**: Cyberpunk green-on-black theme with animations
- **Smart Memory**: Persistent chat history and similarity search
- **Session Management**: Save/load conversations with unique IDs

## 🚀 Quick Start

1. **Set HF Token**: Add your Hugging Face token in Space settings
2. **Select Model**: Choose from available AI models in sidebar
3. **Chat**: Start conversing with Matrix-style streaming
4. **Upload Data**: Add documents via "KNOWLEDGE MATRIX" section

## 🔧 Configuration

### Required Environment Variables
- `HF_TOKEN`: Your Hugging Face API token with inference access

### Supported Models
- **DeepSeek-R1**: Advanced reasoning (Together AI)
- **Llama-3.2-3B**: Efficient local model
- **Qwen2.5-VL-7B**: Vision-language model (Hyperbolic)

## 📋 Usage

### Basic Chat
1. Select AI model from sidebar
2. Enter message in chat input
3. Watch Matrix-style streaming response

### RAG Documents
1. Open "UPLOAD DATA" in sidebar
2. Add title and content
3. Click "INJECT DATA"
4. AI will reference your documents automatically

### Session Controls
- **NEW JACK IN**: Start fresh session
- **PURGE ALL**: Clear all data (double-click to confirm)

## 🛠️ Local Development

```bash
# Clone and install
git clone <repo-url>
pip install streamlit numpy sentence-transformers scikit-learn transformers torch huggingface-hub openai

# Set token and run
export HF_TOKEN="your_token_here"
streamlit run app.py
```

## 🚨 Troubleshooting

**No HF Token Found**
- Add `HF_TOKEN` to Space settings → Repository secrets

**Model Connection Failed**
- Check token validity and quota
- Verify internet connection
- Try different model

**Data Not Saving**
- Ensure sufficient storage space
- Check write permissions

## 📁 Data Storage

- `data/sessions/`: Chat history and metadata
- `data/documents/`: RAG documents and embeddings
- `data/embeddings/`: Vector embeddings for similarity search

All data persists between sessions. Use "PURGE ALL" to reset.

---

*Welcome to the Matrix. The choice is yours.* 🕶️