README.md

metadata

title: STA AI
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.47.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_scopes:
  - inference-api
license: mit
short_description: 'Lightweight Saem’s Tunes assistant — Phi-3.5-mini-instruct '

🎵 Saem's Tunes AI Assistant

Advanced AI-powered assistant for Saem's Tunes music platform, built with Microsoft Phi-3.5-mini-instruct and comprehensive monitoring.

🌟 Features

• Smart FAQ System: AI-powered responses with contextual understanding
• Multi-Platform Deployment: Hugging Face Spaces, Railway, and local deployment
• Continuous Learning: Improves over time with user feedback
• Advanced RAG: Semantic search through your music database
• Real-time Monitoring: Comprehensive performance analytics
• Production Ready: Security, rate limiting, and error handling

🚀 Quick Start

Option 1: Hugging Face Spaces (Recommended - Free)

1. Create a Space at huggingface.co/spaces
2. Upload these files to your Space:
   • app.py (main application)
   • requirements.txt (dependencies)
   • models/phi3.5-mini.Q4_K_M.gguf (download instructions below)
3. Set environment variables in Space settings:
   • SUPABASE_URL: Your Supabase project URL
   • SUPABASE_ANON_KEY: Your Supabase anon key
4. Deploy and your AI assistant will be live!

Option 2: Railway Deployment

1. Connect your GitHub repo to Railway
2. Set environment variables in Railway dashboard
3. Deploy automatically from your repository

Option 3: Local Development

```bash`

Clone and setup

git clone cd saems-tunes-ai

Install dependencies

pip install -r requirements.txt

Download the model

mkdir -p models cd models wget https://huggingface.co/Thetima4/Phi-3.5-mini-instruct-Q4_K_M-GGUF/resolve/main/Phi-3.5-mini-instruct-q4_k_m.gguf

Run locally

python app.py 📦 Model Download The system uses Microsoft Phi-3.5-mini-instruct quantized to Q4_K_M for optimal performance.

Download Command:

bash wget -O models/phi3.5-mini.Q4_K_M.gguf
"https://huggingface.co/Thetima4/Phi-3.5-mini-instruct-Q4_K_M-GGUF/resolve/main/Phi-3.5-mini-instruct-q4_k_m.gguf" Alternative Models: Q4_0: Faster, slightly lower quality

Q5_K_M: Better quality, larger size

Q8_0: Best quality, largest size

🔧 Configuration

Environment Variables:

bash SUPABASE_URL=your_supabase_project_url SUPABASE_ANON_KEY=your_supabase_anon_key HF_SPACE_URL=your_huggingface_space_url MODEL_PATH=./models/phi3.5-mini.Q4_K_M.gguf

Supabase Schema:

Your database should include these tables (see supabase_schema.sql):

songs - Music catalog

artists - Artist information

users - User profiles

ai_interactions - AI conversation logging

🎯 Integration with Your React App Add the AI component to your existing React app:

javascript // In your main App.js import SaemsTunesAI from './components/SaemsTunesAI';

function App() { return (

{/* Your existing components */}

); } 📊 Monitoring & Analytics The system includes comprehensive monitoring:

Real-time Dashboard: Streamlit-based analytics

Performance Metrics: Response times, error rates, token usage

Alert System: Email/Slack notifications for issues

Usage Analytics: User behavior and model performance

Access the dashboard at /dashboard when running locally.

🔒 Security Features Rate Limiting: Prevents API abuse

Input Sanitization: Protects against injection attacks

Audit Logging: Tracks all user interactions

Content Filtering: Detects suspicious queries

🔄 Continuous Learning The system improves over time by:

Collecting feedback from user interactions

Fine-tuning on successful conversations

Automated model updates without downtime

🏗️ Architecture text Frontend (React) → AI API (FastAPI) → Phi-3.5 Model → Supabase Database ↑ Monitoring & Analytics Components: Frontend: React component with chat interface

Backend: FastAPI server with model inference

Database: Supabase for music data and analytics

Monitoring: Comprehensive metrics and alerts

🚨 Troubleshooting Common Issues: Model not loading:

Verify the model file exists in models/

Check file permissions

Ensure enough RAM (4GB+ recommended)

Supabase connection issues:

Verify environment variables

Check Supabase project status

Test database connection

High response times:

Use smaller quantization (Q4_0 instead of Q8_0)

Increase allocated resources

Enable GPU acceleration if available

Getting Help: Check the Hugging Face discussion forum

Open an issue in this repository

Contact the Saem's Tunes development team

📈 Performance Benchmarks Model Size Response Time Quality Use Case Q4_K_M 2.4GB 1-3s Excellent Production Q4_0 2.2GB 1-2s Very Good Fast responses Q8_0 4.2GB 3-5s Best Maximum quality 🔮 Future Enhancements Voice interface integration

Mobile app companion

Advanced music recommendation engine

Multi-language support (Swahili focus)

Band collaboration features

👥 Contributing We welcome contributions! Please see:

Code of Conduct

Contributing Guidelines

Issue Templates

📄 License This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments Microsoft for the Phi-3.5 model

Hugging Face for model hosting and Spaces

Supabase for the database backend

Railway for deployment infrastructure

Built with ❤️ for the Saem's Tunes community

Visit Saem's Tunes | Report an Issue