| # Klooma Recommendation Model |
|
|
| ## What is the Recommendation Model? |
|
|
| The Recommendation System is an advanced AI-powered recommendation engine that provides personalized suggestions across multiple domains. Unlike traditional recommendation systems that focus on a single domain (like movies or products), this model is designed to be a comprehensive life assistant that can recommend anything from entertainment content to security solutions. |
|
|
| ## Model Capabilities |
|
|
| ### 🎯 **Multi-Domain Intelligence** |
| The model excels at providing recommendations across diverse areas: |
|
|
| - **Entertainment**: Movies, TV shows, music, books, games, podcasts |
| - **Lifestyle**: Restaurants, activities, hobbies, travel destinations |
| - **Professional**: Tools, courses, productivity apps, career advice |
| - **Security**: Cybersecurity tools, best practices, threat awareness |
| - **Personal Development**: Learning resources, skill-building activities |
| - **Health & Wellness**: Fitness routines, nutrition advice, mental health resources |
|
|
| ### 🧠 **Context-Aware Understanding** |
| The model doesn't just recommend based on simple preferences - it understands: |
|
|
| - **User Context**: Current situation, mood, available time, location |
| - **Historical Patterns**: Past interactions, preferences, and behaviors |
| - **Environmental Factors**: Weather, time of day, current events |
| - **Personal Constraints**: Budget, dietary restrictions, accessibility needs |
| - **Security Context**: Risk tolerance, threat environment, compliance requirements |
|
|
| ### 🔄 **Interactive & Adaptive** |
| - **Multi-turn Conversations**: Engages in natural dialogue to refine recommendations |
| - **Feedback Integration**: Learns from user responses to improve future suggestions |
| - **Dynamic Updates**: Adapts recommendations based on changing circumstances |
| - **Proactive Suggestions**: Anticipates needs before users explicitly ask |
|
|
| ## How It Works |
|
|
| ### 1. **Input Processing** |
| The model analyzes multiple data points: |
| ``` |
| User Profile: Demographics, preferences, history |
| Current Context: Time, location, mood, activity |
| Constraints: Budget, time, accessibility, security requirements |
| Previous Interactions: What worked, what didn't, feedback patterns |
| ``` |
|
|
| ### 2. **Recommendation Generation** |
| Using advanced language model capabilities, it: |
| - **Analyzes patterns** in user behavior and preferences |
| - **Considers context** to provide situationally relevant suggestions |
| - **Explains reasoning** for each recommendation |
| - **Provides alternatives** with different trade-offs |
| - **Includes actionable steps** for implementation |
|
|
| ### 3. **Output Format** |
| Each recommendation includes: |
| ``` |
| 🎯 Primary Suggestion: Best overall recommendation |
| 📊 Match Score: Relevance percentage (when applicable) |
| 💡 Reasoning: Why this fits the user's needs |
| 🔄 Alternatives: Other good options with different trade-offs |
| ⚡ Next Steps: How to access or implement the recommendation |
| ⚠️ Considerations: Potential drawbacks or requirements |
| ``` |
|
|
| ## Technical Architecture |
|
|
| ### **Base Model** |
| - Built on state-of-the-art language models (LLaMA, Mistral, etc.) |
| - Fine-tuned specifically for recommendation tasks |
| - Optimized for natural conversation and explanation |
|
|
| ### **Training Data** |
| The model is trained on diverse, high-quality examples including: |
| - **18 core recommendation scenarios** covering entertainment, lifestyle, and professional domains |
| - **12 agent-style interactions** for more complex, multi-step recommendations |
| - **Real-world constraints** like budget, time, and accessibility |
| - **Security-aware scenarios** for cybersecurity and threat awareness |
|
|
| ### **Fine-tuning Approach** |
| - **LoRA (Low-Rank Adaptation)**: Efficient training that preserves base model capabilities |
| - **Supervised Fine-tuning**: Trained on high-quality recommendation examples |
| - **Context-aware training**: Examples include rich context for better understanding |
|
|
| ## Use Cases |
|
|
| ### 🏠 **Personal Assistant** |
| - "What should I watch tonight based on my mood?" |
| - "Recommend a restaurant for a date night under $100" |
| - "Suggest productivity tools for remote work" |
|
|
| ### 🛡️ **Security Advisor** |
| - "What cybersecurity practices should I implement for my small business?" |
| - "Recommend tools to protect against current threats" |
| - "Suggest security training for my team" |
|
|
| ### 🎓 **Learning Companion** |
| - "What skills should I learn to advance my career?" |
| - "Recommend courses for someone interested in AI" |
| - "Suggest resources for learning a new language" |
|
|
| ### 🏥 **Wellness Guide** |
| - "Recommend stress management techniques for busy professionals" |
| - "Suggest fitness routines for beginners" |
| - "What mental health resources are available in my area?" |
|
|
| ## Dataset Overview |
|
|
| The `recommendation_demo.json` dataset contains diverse examples of recommendation scenarios including: |
|
|
| - **Content Recommendations**: Movies, TV shows, and streaming content |
| - **Product Recommendations**: E-commerce and shopping suggestions |
| - **Music Recommendations**: Songs, artists, and playlists |
| - **Book Recommendations**: Reading suggestions based on history |
| - **Game Recommendations**: Video game suggestions |
| - **Podcast Recommendations**: Audio content curation |
| - **Restaurant Recommendations**: Dining suggestions |
| - **Multi-turn Conversations**: Interactive recommendation dialogues |
|
|
| ## Dataset Structure |
|
|
| The dataset follows the standard SELF Model Trainer format with three fields: |
|
|
| ```json |
| { |
| "instruction": "The task description or prompt", |
| "input": "User's context, history, and preferences", |
| "output": "The model's recommendation response" |
| } |
| ``` |
|
|
| ### Input Format |
|
|
| Each input typically contains: |
| - **User Profile**: Demographics, membership status, preferences |
| - **History**: Recent interactions (views, purchases, plays, etc.) |
| - **Context**: Current situation (time, mood, activity) |
| - **Constraints**: Budget, dietary restrictions, platform availability |
|
|
| ### Output Format |
|
|
| Recommendations include: |
| - **Primary Recommendations**: Top 3-5 suggestions with explanations |
| - **Match Scores**: Relevance percentages when applicable |
| - **Reasoning**: Why each recommendation fits the user |
| - **Additional Context**: Tips, warnings, or usage suggestions |
|
|
|
|
|
|
| ### 1. Training with the Dataset |
|
|
| ```bash |
| # Fine-tune a model using LoRA |
| python src/train.py \ |
| --model_name_or_path meta-llama/Llama-3-7b-hf \ |
| --dataset recommendation_demo \ |
| --output_dir ./saves/recommendation_model \ |
| --overwrite_cache \ |
| --template default \ |
| --finetuning_type lora \ |
| --lora_target q_proj,v_proj \ |
| --per_device_train_batch_size 4 \ |
| --gradient_accumulation_steps 4 \ |
| --lr_scheduler_type cosine \ |
| --logging_steps 10 \ |
| --save_steps 1000 \ |
| --learning_rate 5e-5 \ |
| --num_train_epochs 3.0 \ |
| --plot_loss \ |
| --fp16 |
| ``` |
|
|
| ### 2. Using in Web UI |
|
|
| 1. Start the web interface: |
| ```bash |
| python src/webui.py |
| ``` |
|
|
| 2. In the training tab: |
| - Select your base model |
| - Choose "recommendation_demo" from the dataset dropdown |
| - Configure training parameters |
| - Start training |
| |
| ### 3. Inference Example |
| |
| ```python |
| from modeltrainer.chat import ChatModel |
| |
| # Load the fine-tuned model |
| model = ChatModel(args={ |
| "model_name_or_path": "meta-llama/Llama-2-7b-hf", |
| "adapter_name_or_path": "./saves/recommendation_model", |
| "template": "default", |
| "finetuning_type": "lora" |
| }) |
| |
| # Generate recommendations |
| messages = [{ |
| "role": "user", |
| "content": """Based on my history, what should I watch next? |
| Recent watches: Breaking Bad, Better Call Saul, Ozark |
| Preferences: Crime dramas, complex characters, no sci-fi""" |
| }] |
| |
| response = model.chat(messages) |
| print(response) |
| ``` |
| |
| ## Extending the Dataset |
| |
| ### Adding New Examples |
| |
| 1. Follow the existing format: |
| ```json |
| { |
| "instruction": "Recommend [type] based on the user's [context]", |
| "input": "Detailed user information...", |
| "output": "Structured recommendations..." |
| } |
| ``` |
| |
| 2. Include diverse scenarios: |
| - Different user profiles |
| - Various contexts and constraints |
| - Multiple recommendation types |
| |
| ### Best Practices |
| |
| 1. **Detailed Inputs**: Include rich context about the user |
| 2. **Explained Outputs**: Always provide reasoning for recommendations |
| 3. **Structured Responses**: Use consistent formatting with headers and sections |
| 4. **Personalization**: Reference specific user preferences in recommendations |
| 5. **Actionable Suggestions**: Include next steps or how to access recommendations |
| |
| ## Training Tips |
| |
| ### Hyperparameters |
| - **Learning Rate**: 5e-5 to 1e-4 for LoRA fine-tuning |
| - **Batch Size**: 4-8 depending on GPU memory |
| - **Epochs**: 2-3 epochs usually sufficient |
| - **LoRA Rank**: 8-16 for recommendation tasks |
| |
| ### Data Augmentation |
| Consider augmenting the dataset with: |
| - Negative examples (what NOT to recommend) |
| - Edge cases (limited options, conflicting preferences) |
| - Follow-up interactions (user feedback on recommendations) |
| |
| ## Evaluation |
| |
| ### Metrics to Track |
| 1. **Relevance**: Do recommendations match user preferences? |
| 2. **Diversity**: Are recommendations varied enough? |
| 3. **Explanation Quality**: Are reasons clear and logical? |
| 4. **Format Consistency**: Does output follow expected structure? |
| |
| ### Testing Prompts |
| ```python |
| test_prompts = [ |
| "I love sci-fi movies but hate horror. What should I watch?", |
| "Recommend music for studying. I usually listen to lo-fi hip hop.", |
| "Suggest games like Zelda but for PC.", |
| "What restaurants in Seattle serve good vegetarian food?" |
| ] |
| ``` |
| |
| ## Common Issues and Solutions |
| |
| ### Issue: Generic Recommendations |
| **Solution**: Ensure training data has specific user details and the model is referencing them |
| |
| ### Issue: Format Inconsistency |
| **Solution**: Use more epochs or adjust the template to enforce structure |
| |
| ### Issue: Lack of Reasoning |
| **Solution**: Every training example should include "Why" explanations |
| |
| ## Dataset Statistics |
| |
| - Total Examples: 10 comprehensive scenarios |
| - Average Input Length: ~200 tokens |
| - Average Output Length: ~400 tokens |
| - Domains Covered: 8 (entertainment, shopping, dining, etc.) |
| |
| ## License and Attribution |
| |
| This dataset is created for demonstration and educational purposes. When using for production: |
| 1. Expand with domain-specific examples |
| 2. Include real user feedback loops |
| 3. Consider privacy and bias implications |
| 4. Add examples from your specific use case |
| |
| ## Contributing |
| |
| To contribute new examples: |
| 1. Follow the existing format precisely |
| 2. Ensure high-quality, realistic scenarios |
| 3. Include diverse user profiles |
| 4. Test with the base model first |
| 5. Submit PR with at least 5 new examples |
| |
| ## Related Resources |
| |
| - [AuRA 1.0 (https://selflabs.xyz) |
| - [Fine-tuning Best Practices](https://huggingface.co/docs/transformers/training) |
| - [Recommendation Systems Papers](https://paperswithcode.com/task/recommendation-systems) |
