Add Local LLM setup instructions and exclude model files from Git

- Add comprehensive download instructions in models/README.md
- Exclude LLM model files from Git (.gitignore)
- Update main README with model download commands
- Add .gitkeep to preserve models/ directory structure
- Remove large model file from Git tracking

Author: AlexTkDev

.gitignore

@@ -174,6 +174,14 @@ db.json
 *.png
 /plans/
 
+# Local LLM models (too large for Git)
+models/*.gguf
+models/*.bin
+models/*.safetensors
+models/*.pth
+models/*.pt
+models/*.ckpt
+
 # Test artifacts
 *.tmp
 *.log

README.md

@@ -114,6 +114,21 @@ The bot includes a local TinyLlama 1.1B model for offline operation:
 - **Size**: ~1.1GB
 - **Requirements**: ~2GB RAM for optimal performance
 
+**Important**: The model file is not included in the repository due to size limitations. You must download it separately:
+
+```bash
+# Download the model (choose one method)
+# Option 1: Using wget
+wget -O models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
+    "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
+
+# Option 2: Using curl
+curl -L -o models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
+    "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
+```
+
+See [models/README.md](models/README.md) for detailed download instructions and troubleshooting.
+
 The model is automatically loaded at startup and provides offline fallback capability.
 
 ### 4. Create .env file

models/.gitkeep

@@ -0,0 +1,3 @@
+# This file ensures the models/ directory is tracked by Git
+# The actual LLM model files are ignored due to size limitations
+# See README.md for download instructions

models/README.md

@@ -0,0 +1,130 @@
+# Local LLM Models
+
+This directory contains the local language model used by EduPlannerBotAI for offline operation.
+
+## Required Model
+
+**Model**: TinyLlama 1.1B Chat v1.0  
+**Format**: GGUF (quantized)  
+**Size**: ~1.1GB  
+**Quantization**: Q4_K_M (4-bit, optimized for memory and speed)
+
+## Download Instructions
+
+### Option 1: Direct Download from Hugging Face
+
+1. Visit the model page: [TinyLlama-1.1B-Chat-v1.0-GGUF](https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF)
+2. Download the file: `tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf`
+3. Place it in this `models/` directory
+4. Ensure the filename matches exactly: `tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf`
+
+### Option 2: Using Hugging Face CLI
+
+```bash
+# Install huggingface-hub if not already installed
+pip install huggingface-hub
+
+# Download the model
+huggingface-cli download TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF \
+    tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
+    --local-dir models/
+```
+
+### Option 3: Using wget/curl
+
+```bash
+# Using wget
+wget -O models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
+    "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
+
+# Using curl
+curl -L -o models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
+    "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
+```
+
+## File Structure
+
+After downloading, your directory should look like this:
+
+```
+models/
+├── README.md
+└── tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf  # ~1.1GB
+```
+
+## Verification
+
+Verify the model is correctly downloaded:
+
+```bash
+# Check file exists and size
+ls -lh models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
+
+# Expected output:
+# -rw-r--r-- 1 user user 1.1G Jan 1 12:00 tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
+
+# Check file integrity (optional)
+file models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
+```
+
+## Model Specifications
+
+- **Architecture**: TinyLlama 1.1B (Llama architecture)
+- **Training Data**: Chat/instruction fine-tuned
+- **Context Length**: 2048 tokens
+- **Quantization**: Q4_K_M (4-bit, optimized)
+- **Memory Usage**: ~2GB RAM during inference
+- **Performance**: Good quality for study plan generation
+
+## Troubleshooting
+
+### Model Not Found Error
+```
+[Local LLM error: Model not loaded]
+```
+**Solution**: Ensure the model file is in the correct location with the exact filename.
+
+### Memory Issues
+```
+[Local LLM error: Out of memory]
+```
+**Solution**: 
+- Ensure you have at least 2GB RAM available
+- Close other memory-intensive applications
+- Consider using a smaller model variant
+
+### Slow Performance
+**Solutions**:
+- Ensure you have a multi-core CPU
+- Close unnecessary background processes
+- The first request may be slower due to model loading
+
+## Alternative Models
+
+If you prefer a different model, you can use any GGUF format model:
+
+1. **Llama 2 7B**: Better quality, larger size (~4GB)
+2. **Mistral 7B**: Excellent performance, medium size (~4GB)
+3. **Phi-2**: Good quality, smaller size (~1.4GB)
+
+**Note**: Update the model path in `services/local_llm.py` if using a different model.
+
+## Performance Tips
+
+- **First Run**: The first request will be slower as the model loads into memory
+- **Subsequent Requests**: Much faster after initial loading
+- **Memory**: Keep at least 2GB RAM free for optimal performance
+- **CPU**: Multi-core processors will improve inference speed
+
+## Support
+
+If you encounter issues with the local LLM:
+
+1. Check the bot logs for detailed error messages
+2. Verify the model file is correctly placed
+3. Ensure sufficient system resources
+4. Open an issue on GitHub with error details
+
+## License
+
+The TinyLlama model is licensed under Apache 2.0. See the [Hugging Face page](https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF) for full license details.