Spaces:
Running
Running
metadata
title: Yashgori
emoji: 🚀
colorFrom: blue
colorTo: gray
sdk: docker
sdk_version: 0.0.1
app_file: app.py
pinned: false
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
🤖 Yash Gori AI Portfolio API v2.0 - Complete Implementation Guide
Overview
This is a sophisticated AI portfolio chatbot that intelligently adapts to different types of visitors (recruiters, developers, students, etc.) and provides personalized responses about Yash Gori's skills, projects, and qualifications.
🎯 Complete Features Implemented (A to Z)
Core AI Intelligence
- ✅ Intelligent AI Agent with personality using Groq Llama 3.3 70B
- ✅ User Intent Detection (recruiter/technical/collaborator/student/general)
- ✅ Sophistication Level Analysis (beginner/intermediate/advanced)
- ✅ Dynamic Response Adaptation based on user type and context
- ✅ Natural Language Processing with context understanding
Conversation Management
- ✅ Session Management with UUID-based session IDs
- ✅ Conversation Memory building context over multiple exchanges
- ✅ Topic Tracking and theme analysis
- ✅ Question Clarity Detection with clarifying question generation
- ✅ Follow-up Engagement prompts to continue conversations
Smart Features
- ✅ Smart Suggestions based on conversation flow patterns
- ✅ Rich Content Integration with contextual project details
- ✅ Project Mention Detection with GitHub links
- ✅ Contextual Information delivery based on questions
- ✅ Intelligent Fallback Responses when AI unavailable
Rate Limiting & Security
- ✅ Multi-level Rate Limiting (IP-based: 60/hour, Session-based: 20/hour)
- ✅ Background Session Cleanup every 10 minutes
- ✅ Rate Limit Headers in responses
- ✅ IP Address Tracking (partially masked for privacy)
Database & Analytics
- ✅ SQLite Database with visitor tracking
- ✅ User Profile Storage with conversation history
- ✅ Real-time Analytics collection
- ✅ Daily Analytics Summaries with trends
- ✅ Comprehensive Dashboard with insights
- ✅ Data Export capabilities for analysis
API Structure
- ✅ RESTful API Design with proper HTTP methods
- ✅ Enhanced JSON Responses with metadata
- ✅ Error Handling with fallback responses
- ✅ CORS Support for frontend integration
- ✅ Database Migration system for schema updates
🔄 Complete Workflow
1. User Interaction Flow
User Visits → Session Created → Question Asked → AI Processing → Response Generation → Analytics Saved → Smart Suggestions Provided
2. Behind-the-Scenes Process
1. Session Management:
- Generate/retrieve session ID
- Check rate limits (IP + Session)
- Load conversation memory
2. User Analysis:
- Detect user intent (recruiter/technical/etc.)
- Analyze sophistication level
- Check question clarity
3. Context Building:
- Retrieve conversation history
- Build context summary
- Detect mentioned projects
4. AI Response Generation:
- Create intelligent agent prompt
- Call Groq API with context
- Process and validate response
5. Intelligence Layer:
- Generate smart suggestions
- Extract rich content
- Analyze conversation flow
6. Data Persistence:
- Save conversation to database
- Update user profile
- Update daily analytics
7. Response Assembly:
- Build comprehensive JSON response
- Include metadata and suggestions
- Apply rate limit headers
🛠 Complete API Routes
1. Main Chat Endpoint
POST /ask
Request:
{
"question": "What are Yash's technical skills?",
"session_id": "optional-uuid-here"
}
Response:
{
"success": true,
"api_version": "2.0",
"session": {
"session_id": "1e9704c6-eecb-4d32-9066-d8d62c9d9682",
"conversation_number": 3,
"user_status": "returning",
"session_created": "2025-08-10T21:00:00"
},
"request": {
"question": "What are Yash's technical skills?",
"processed_at": "2025-08-10T21:18:00",
"response_time_ms": null
},
"response": {
"answer": "Yash has strong technical skills in AI/ML, Python, Flask, RAG systems...",
"model_used": "openai/gpt-oss-120b",
"confidence_indicators": {
"question_clarity": 0.9,
"user_type_confidence": 0.8,
"response_relevance": 0.9
}
},
"intelligence": {
"user_analysis": {
"detected_type": "technical",
"sophistication_level": "intermediate",
"question_clarity": "Clear technical inquiry",
"is_returning_user": true,
"previous_topics": ["skills", "projects"]
},
"conversation_state": {
"total_exchanges": 3,
"main_themes": ["technical_skills", "ai_projects"],
"user_progression": ["exploring", "deepening"],
"conversation_depth": "moderate"
},
"smart_suggestions": {
"follow_up_questions": [
"Would you like to see specific examples of his AI projects?",
"How do his skills align with your team's needs?"
],
"topic_transitions": [
"Let's dive deeper into the area that interests you most"
],
"depth_exploration": [
"Want to discuss the system architecture in detail?"
]
}
},
"rich_content": {
"DocuTalk": {
"github_link": "https://github.com/yashnileshgori/DocuTalk",
"technical_specs": ["RAG", "LangChain", "Streamlit"],
"key_achievement": "Conversational document AI"
}
},
"metadata": {
"rate_limit": {
"requests_remaining": 58,
"window_reset": "2025-08-10T22:18:00"
},
"developer": "Yash Gori",
"timestamp": "2025-08-10T21:18:00"
}
}
2. API Information
GET /
Response:
{
"message": "Welcome to Yash Gori's AI Portfolio API",
"version": "2.0",
"developer": "Yash Gori",
"description": "Intelligent portfolio chatbot with adaptive responses",
"endpoints": {
"POST /ask": "Main chat endpoint",
"GET /profile": "Complete profile data",
"GET /analytics/dashboard": "Analytics dashboard"
}
}
3. Complete Profile
GET /profile
Response:
{
"success": true,
"developer": "Yash Gori",
"profile": {
"personal_info": {
"name": "Yash Gori",
"email": "[email protected]",
"phone": "+91-XXXXXXXXXX"
},
"current_position": {
"role": "AI Engineer Intern",
"company": "Webotix IT Consultancy"
},
"education": {
"current": {
"degree": "BTech in Information Technology",
"college": "KJ Somaiya College of Engineering",
"cgpa": "8.12"
}
}
}
}
4. Session State
GET /session/{session_id}/state
Response:
{
"success": true,
"session_id": "uuid-here",
"session_exists": true,
"profile": {
"primary_type": "technical",
"sophistication_level": "intermediate",
"conversation_count": 5
},
"conversation_memory": {
"total_exchanges": 5,
"main_themes": ["skills", "projects"],
"conversation_depth": "deep"
}
}
5. Session History
GET /session/{session_id}/history
Response:
{
"success": true,
"session_id": "uuid-here",
"total_conversations": 5,
"conversation_history": [
{
"turn": 1,
"timestamp": "2025-08-10T21:00:00",
"question": "What are Yash's skills?",
"answer": "Yash has strong technical skills...",
"user_type": "technical",
"sophistication": "intermediate"
}
]
}
6. Analytics Dashboard
GET /analytics/dashboard
Response:
{
"success": true,
"dashboard_title": "Yash Gori's AI Portfolio Analytics Dashboard",
"generated_at": "2025-08-10T21:18:00",
"overview": {
"total_conversations": 150,
"unique_visitors": 45,
"avg_question_length": 25.5,
"avg_answer_length": 180.2
},
"user_types": {
"recruiter": 30,
"technical": 45,
"general": 75
},
"engagement_metrics": {
"avg_conversations_per_session": 2.3,
"multi_turn_sessions": 20,
"highly_engaged_sessions": 8
},
"summary_insights": {
"engagement_rate": 3.33,
"top_user_type": "technical",
"peak_activity_hour": "14"
}
}
7. Session Analytics
GET /analytics/session/{session_id}
Response:
{
"success": true,
"session_id": "uuid-here",
"conversation_count": 5,
"user_journey": [
{
"turn": 1,
"question": "What are Yash's skills?",
"detected_type": "technical",
"sophistication": "intermediate"
}
],
"topics_explored": ["DocuTalk", "Finance Advisor"],
"detected_user_types": ["technical", "recruiter"]
}
8. Daily Analytics
GET /analytics/daily
Response:
{
"success": true,
"daily_analytics": [
{
"date": "2025-08-10",
"total_conversations": 25,
"unique_sessions": 12,
"user_type_breakdown": {"technical": 10, "recruiter": 8},
"avg_conversation_length": 150
}
],
"trends": {
"conversation_trend": 5,
"session_trend": 2
}
}
9. Export Analytics
GET /analytics/export
Response:
{
"success": true,
"export_metadata": {
"generated_at": "2025-08-10T21:18:00",
"total_records": 150,
"analytics_version": "2.0"
},
"full_analytics": { /* Complete analytics data */ },
"conversation_records": [ /* All conversations */ ]
}
10. Admin Conversations
GET /admin/conversations
Response:
{
"success": true,
"total_conversations": 150,
"conversations": [
{
"id": "uuid",
"session_id": "session-uuid",
"timestamp": "2025-08-10T21:00:00",
"user_type": "technical",
"question": "What are Yash's skills?",
"answer": "Yash has strong technical skills..."
}
]
}
11. Admin Profiles
GET /admin/profiles
Response:
{
"success": true,
"total_unique_visitors": 45,
"profiles": [
{
"session_id": "uuid",
"primary_type": "technical",
"conversation_count": 5,
"first_seen": "2025-08-10T20:00:00",
"last_seen": "2025-08-10T21:00:00"
}
],
"analytics": {
"user_types": {"technical": 20, "recruiter": 15},
"skill_levels": {"intermediate": 25, "advanced": 10}
}
}
🖥 Frontend Integration Guide
1. Essential Frontend Components
Chat Interface
class YashChatbot {
constructor() {
this.sessionId = localStorage.getItem('yashChatSession') || null;
this.apiBase = 'YOUR_API_URL';
}
async sendMessage(question) {
const payload = {
question: question,
session_id: this.sessionId
};
const response = await fetch(`${this.apiBase}/ask`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
});
const data = await response.json();
// Store session ID for continuity
if (!this.sessionId && data.session?.session_id) {
this.sessionId = data.session.session_id;
localStorage.setItem('yashChatSession', this.sessionId);
}
return data;
}
}
Message Display
function displayMessage(data) {
// Main response
addMessage(data.response.answer, 'bot');
// Smart suggestions as quick reply buttons
if (data.intelligence?.smart_suggestions?.follow_up_questions) {
showQuickReplies(data.intelligence.smart_suggestions.follow_up_questions);
}
// Rich content for projects
if (data.rich_content) {
displayProjectCards(data.rich_content);
}
// User type indicator (optional)
if (data.intelligence?.user_analysis?.detected_type !== 'general') {
showUserTypeIndicator(data.intelligence.user_analysis.detected_type);
}
}
2. Required Frontend Features
Session Management
- Store
session_idin localStorage - Include in all subsequent requests
- Handle session restoration
Rate Limit Handling
function handleRateLimit(data) {
if (data.metadata?.rate_limit?.requests_remaining < 5) {
showWarning(`${data.metadata.rate_limit.requests_remaining} requests remaining`);
}
}
Smart Suggestions
function showQuickReplies(suggestions) {
const container = document.getElementById('quick-replies');
container.innerHTML = '';
suggestions.forEach(suggestion => {
const button = document.createElement('button');
button.textContent = suggestion;
button.onclick = () => sendMessage(suggestion);
container.appendChild(button);
});
}
Rich Content Display
function displayProjectCards(richContent) {
Object.entries(richContent).forEach(([projectName, details]) => {
const card = createProjectCard({
name: projectName,
github: details.github_link,
specs: details.technical_specs,
achievement: details.key_achievement
});
document.getElementById('rich-content').appendChild(card);
});
}
3. Error Handling
async function handleApiCall(question) {
try {
const data = await chatbot.sendMessage(question);
if (data.success) {
displayMessage(data);
handleRateLimit(data);
} else {
// Show fallback response
if (data.fallback_answer) {
addMessage(data.fallback_answer, 'bot');
}
}
} catch (error) {
addMessage("Sorry, I'm having trouble connecting. Please try again.", 'bot');
}
}
4. Analytics Integration (Optional)
// For admin dashboard
async function loadAnalytics() {
const response = await fetch(`${apiBase}/analytics/dashboard`);
const analytics = await response.json();
displayAnalyticsDashboard(analytics);
}
// For session insights
async function showSessionInsights(sessionId) {
const response = await fetch(`${apiBase}/analytics/session/${sessionId}`);
const insights = await response.json();
displaySessionJourney(insights.user_journey);
}
🔧 Technical Implementation Notes
Database Schema
-- Main conversations table
CREATE TABLE visitors (
id TEXT PRIMARY KEY,
session_id TEXT,
timestamp TEXT,
user_type TEXT,
question TEXT,
answer TEXT,
user_info TEXT,
ip_address TEXT
);
-- User profiles table
CREATE TABLE user_profiles (
session_id TEXT PRIMARY KEY,
primary_type TEXT,
sophistication_level TEXT,
interests TEXT,
conversation_count INTEGER,
first_seen TEXT,
last_seen TEXT,
profile_data TEXT
);
-- Daily analytics table
CREATE TABLE daily_analytics (
date TEXT PRIMARY KEY,
total_conversations INTEGER,
unique_sessions INTEGER,
user_type_breakdown TEXT,
avg_conversation_length INTEGER,
top_questions TEXT,
updated_at TIMESTAMP
);
Key Configuration
# API Configuration
GROQ_API_KEY = "your-groq-api-key"
DB_PATH = "/tmp/visitors.db"
# Rate Limits
IP_RATE_LIMIT = 60 # per hour
SESSION_RATE_LIMIT = 20 # per hour
# Session Configuration
SESSION_TIMEOUT = 1800 # 30 minutes
CLEANUP_INTERVAL = 600 # 10 minutes
Environment Variables
GROQ_API_KEY=your_groq_api_key_here
PORT=7860
SQLITE_DB_PATH=/tmp/visitors.db
🚀 Deployment Checklist
Backend (Flask API)
- ✅ Valid Groq API key configured
- ✅ Database migrations applied
- ✅ CORS configured for frontend domain
- ✅ Rate limiting active
- ✅ Background cleanup running
- ✅ Analytics collection enabled
Frontend Integration
- ✅ API endpoint configured correctly
- ✅ Session management implemented
- ✅ Error handling for API failures
- ✅ Smart suggestions display
- ✅ Rich content rendering
- ✅ Rate limit handling
Testing
- ✅ Test different user types (recruiter/technical/general)
- ✅ Verify conversation memory works
- ✅ Check smart suggestions appear
- ✅ Confirm analytics are collected
- ✅ Test rate limiting behavior
- ✅ Verify session continuity
📊 Success Metrics
The API provides detailed metrics to measure success:
- Engagement Rate: Conversations per unique visitor
- User Type Distribution: Which types of users visit most
- Conversation Depth: How many exchanges per session
- Popular Topics: Most asked questions
- Peak Activity: Best times for engagement
- Return Visitors: Session continuity tracking
This comprehensive AI portfolio chatbot transforms basic interactions into intelligent, personalized conversations that adapt to each visitor's needs while providing deep insights into user engagement patterns.