README.md

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:

{
  "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

# 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:

   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

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:

{
  "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

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
• Recommendation Systems Papers