Added documentation testing

app.py

@@ -32,6 +32,7 @@ class LearningSession:
     end_time: Optional[datetime] = None
     words_learned: int = 0
     idioms_learned: int = 0
+    proverbs_learned: int = 0
     grammar_learned: int = 0 
     questions_asked: int = 0
 
@@ -64,6 +65,7 @@ class PersonalizedLearningTracker:
             end_time TEXT,
             words_learned INTEGER DEFAULT 0,
             idioms_learned INTEGER DEFAULT 0,
+            proverbs_learned INTEGER DEFAULT 0, 
             grammar_learned INTEGER DEFAULT 0,
             questions_asked INTEGER DEFAULT 0
         )
@@ -233,6 +235,25 @@ class PersonalizedLearningTracker:
             WHERE user_id = ? AND word = ? AND category = ?
         ''', (mastery_level, user_id, normalized_word, category))
         
+        if category == "word":
+            cursor.execute('''
+                UPDATE learning_sessions 
+                SET words_learned = words_learned + 1 
+                WHERE user_id = ? AND end_time IS NULL
+            ''', (user_id,))
+        elif category == "idiom":
+            cursor.execute('''
+                UPDATE learning_sessions 
+                SET idioms_learned = idioms_learned + 1 
+                WHERE user_id = ? AND end_time IS NULL
+            ''', (user_id,))
+        elif category == "proverb": 
+            cursor.execute('''
+                UPDATE learning_sessions 
+                SET proverbs_learned = proverbs_learned + 1 
+                WHERE user_id = ? AND end_time IS NULL
+            ''', (user_id,))
+        
         conn.commit()
         conn.close()
     
@@ -374,6 +395,9 @@ class PersonalizedLearningTracker:
         if 'idiom' not in progress['category_stats'] or progress['category_stats'].get('idiom', {}).get('count', 0) < 5:
             recommendations.append("Explore Kazakh idioms to improve your cultural understanding!")
         
+        if 'proverb' not in progress['category_stats'] or progress['category_stats'].get('proverb', {}).get('count', 0) < 5: 
+            recommendations.append("Learn Kazakh proverbs to deepen your cultural knowledge!")
+        
         words_to_review = self.get_words_to_review(user_id, 5)
         if words_to_review:
             recommendations.append(f"Review these words: {', '.join([w['word'] for w in words_to_review[:3]])}")
@@ -456,7 +480,7 @@ class PersonalizedKazakhAssistant:
                     
                     if term:
                         self.known_terms.add(term)
-                        if definition == "тыныш отыру":
+                        if definition == "құстар туралы (мақал-мәтел)":
                             print(f"Loaded 'тыныш отыру' idiom: '{term}' from {doc_type} folder")
         
         print(f"Loaded {len(self.known_terms)} known terms: {list(self.known_terms)[:10]}")  
@@ -476,25 +500,25 @@ class PersonalizedKazakhAssistant:
 
     def setup_llm(self, target_language: str = "English"):
         self.system_prompt = f"""
-        You are a personalized Kazakh language learning assistant with access to a comprehensive knowledge base and user learning history. Your role is to help users learn Kazakh words and idioms while tracking their progress and providing personalized recommendations. Respond in {target_language}.
+        You are a personalized Kazakh language learning assistant with access to a comprehensive knowledge base and user learning history. Your role is to help users learn Kazakh words, idioms, and proverbs while tracking their progress and providing personalized recommendations. Respond in {target_language}.
 
         Key capabilities:
-        1. *Answer Queries*: Provide accurate definitions and examples for Kazakh words and idioms.
-        2. *Track Learning Progress*: Identify and track when users learn new words or idioms.
+        1. *Answer Queries*: Provide accurate definitions and examples for Kazakh words, idioms, and proverbs.
+        2. *Track Learning Progress*: Identify and track when users learn new words, idioms, or proverbs.
         3. *Personalized Responses*: Adapt responses based on user's learning history.
         4. *Progress Reporting*: Provide detailed progress reports when asked.
-        5. *Learning Recommendations*: Suggest words/idioms to review or learn next.
+        5. *Learning Recommendations*: Suggest words, idioms, or proverbs to review or learn next.
 
         Response Guidelines:
-        - For word/idiom queries: Provide definition, usage examples, and related information in {target_language}.
-        - When explaining a Kazakh word or idiom retrieved from the knowledge base, **bold** the term (e.g., **күләпара**) in the response to highlight it.
-        - Only bold the main term or idiom being explained, not other Kazakh words.
-        - Always identify the main Kazakh word/idiom for progress tracking.
+        - For word, idiom, or proverb queries: Provide definition, usage examples, and related information in {target_language}.
+        - When explaining a Kazakh word, idiom, or proverb retrieved from the knowledge base, **bold** the entire term (e.g., **күләпара**, **дәм-ауыз тигізу**, **Құс қанатымен ұшады, құйрығымен қонады**) in the response to highlight it using double asterisks (**).
+        - Only bold the main term, idiom, or proverb being explained, not other Kazakh words or partial phrases, if multiple idioms or proverbs were requested **bold** each of them.
+        - Always identify the main Kazakh word, idiom, or proverb for progress tracking.
         - *RAG Usage*:
-        - Use Retrieval-Augmented Generation (RAG) only when the query explicitly asks for explanations of specific Kazakh terms or idioms (e.g., "What does сәлем mean?") or when the context strongly suggests a need for knowledge base information (e.g., queries about specific words or idioms).
-        - When using RAG, limit the response to explaining 1-2 distinct terms at most, unless the user explicitly asks for multiple terms (e.g., "List several idioms"). For each term, provide 3-4 relevant examples. Do not list all or many terms or matches from the knowledge base.
+        - Use Retrieval-Augmented Generation (RAG) only when the query explicitly asks for explanations of specific Kazakh terms, idioms, or proverbs (e.g., "What does сәлем mean?", "Tell me about a Kazakh proverb") or when the context strongly suggests a need for knowledge base information.
+        - When using RAG, limit the response to explaining 1-2 distinct terms, idioms, or proverbs at most, unless the user explicitly asks for multiple terms (e.g., "List several proverbs"). For each term, provide 3-4 relevant examples. Do not list all or many terms or matches from the knowledge base.
         - For general queries (e.g., greetings, procedural questions, or commands like /progress) or grammar-related queries (e.g., "explain me nouns"), rely on your general knowledge and do not use RAG unless the knowledge base contains relevant information.
-        - Since the knowledge base contains only words and idioms, grammar explanations (e.g., about nouns, verbs) should be provided using your own knowledge, without relying on RAG, unless the query specifically involves terms in the knowledge base.
+        - Since the knowledge base contains only words, idioms, and proverbs, grammar explanations (e.g., about nouns, verbs) should be provided using your own knowledge, without relying on RAG, unless the query specifically involves terms in the knowledge base.
         - Be encouraging and supportive.
         - Use simple, clear explanations.
         - When discussing progress, be specific and motivating.
@@ -512,14 +536,14 @@ class PersonalizedKazakhAssistant:
         )
         
     def normalize_term(self, term: str) -> str:
-        return ' '.join(term.lower().strip().split())
+        return ' '.join(term.replace(',', '').lower().strip().split())
     
     def extract_kazakh_terms(self, message: str, response: str) -> List[Tuple[str, str, str]]:
         terms = []
         seen_terms = set()
         
         try:
-            retrieved_docs = self.vectorstore.similarity_search(message, k=5)
+            retrieved_docs = self.vectorstore.similarity_search(message, k=15)
             bold_pattern = r'(?:\*\*|__)([А-Яа-яӘәҒғҚқҢңӨөҰұҮүҺһІі\s,-]+)(?:\*\*|__)(?=\s|$|[:.,!?)])'
             bold_matches = re.findall(bold_pattern, response, re.UNICODE)
             
@@ -543,30 +567,40 @@ class PersonalizedKazakhAssistant:
                         for doc in retrieved_docs:
                             doc_type = doc.metadata.get('doc_type', '').lower()
                             if normalized_term in self.normalize_term(doc.page_content):
-                                if 'idioms' in doc_type or 'тіркес' in doc_type:
+                                if 'proverbs' in doc_type:
+                                    category = "proverb"
+                                elif 'idioms' in doc_type or 'тіркес' in doc_type:
                                     category = "idiom"
-                                elif 'words' in doc_type:
+                                else:
                                     category = "word"
-                                elif 'grammar' in doc_type:
-                                    category = "grammar"
                                 definition = self.extract_clean_definition(normalized_term, doc.page_content, response)
                                 break
                         if not definition:
                             if len(known_term.split()) > 1:
-                                category = "idiom"
+                                category = "proverb" if any('proverbs' in doc.metadata.get('doc_type', '').lower() for doc in retrieved_docs) else "idiom"
                                 definition = self.extract_clean_definition(normalized_term, "", response)
                         break
                 
                 if not term_matched and len(term.split()) > 1:
-                    category = "idiom"
-                    definition = self.extract_clean_definition(normalized_term, "", response)
-                    term_matched = True
-                elif not term_matched:
+                    for doc in retrieved_docs:
+                        doc_type = doc.metadata.get('doc_type', '').lower()
+                        if 'proverbs' in doc_type and normalized_term in self.normalize_term(doc.page_content):
+                            category = "proverb"
+                            definition = self.extract_clean_definition(normalized_term, doc.page_content, response)
+                            term_matched = True
+                            break
+                        elif 'idioms' in doc_type and normalized_term in self.normalize_term(doc.page_content):
+                            category = "idiom"
+                            definition = self.extract_clean_definition(normalized_term, doc.page_content, response)
+                            term_matched = True
+                            break
+                
+                if not term_matched:
                     category = "word"
                     definition = self.extract_clean_definition(normalized_term, "", response)
                     term_matched = True
                 
-                if term_matched and definition:
+                if term_matched and definition and not definition.startswith("Definition for"):
                     terms.append((original_term, category, definition))
                     seen_terms.add(normalized_term)
                     print(f"Added bolded term: {original_term}, category: {category}, definition: {definition}")
@@ -582,7 +616,7 @@ class PersonalizedKazakhAssistant:
     def extract_clean_definition(self, term: str, doc_content: str, response: str) -> str:
         normalized_term = self.normalize_term(term)
         
-        retrieved_docs = self.vectorstore.similarity_search(term, k=5)
+        retrieved_docs = self.vectorstore.similarity_search(term, k=15)
         for doc in retrieved_docs:
             lines = doc.page_content.replace('\r\n', '\n').replace('\r', '\n').split('\n')
             for line in lines:
@@ -592,6 +626,16 @@ class PersonalizedKazakhAssistant:
                     if self.normalize_term(doc_term) == normalized_term:
                         return doc_definition
         
+        lines = response.split('\n')
+        for line in lines:
+            line = line.strip()
+            if f'**{term}**' in line and ':' in line:
+                parts = line.split(':', 1)
+                if len(parts) > 1:
+                    definition = parts[1].strip()
+                    if definition:
+                        return definition
+        
         return f"Definition for {term}"
     
     def get_user_memory(self, user_id: str):
@@ -653,7 +697,7 @@ class PersonalizedKazakhAssistant:
         elif message.lower().startswith('/help'):
             return self.get_help_message()
 
-        retrieved_docs = self.vectorstore.similarity_search(message, k=5)
+        retrieved_docs = self.vectorstore.similarity_search(message, k=15)
         context = "\n".join([doc.page_content for doc in retrieved_docs])
         
         memory = self.get_user_memory(user_id)
@@ -703,14 +747,14 @@ class PersonalizedKazakhAssistant:
         
         User question: {message}
         
-        Respond in {target_language}. If explaining a Kazakh word or idiom retrieved from the context, **bold** the term (e.g., **күләпара**) in your response to highlight it using double asterisks (**). Only bold the main term being explained.
+        Respond in {target_language}. If explaining a Kazakh word, idiom or proverb retrieved from the context, **bold** the term (e.g., **күләпара**) in your response to highlight it using double asterisks (**). Only bold the main term being explained.
         """
         
         try:
             if not hasattr(self.llm, 'generate_content'):
                 raise AttributeError("LLM does not have generate_content method")
             response = self.llm.generate_content(full_prompt).text
-            # print(f"Full LLM response:\n{response}\n{'-'*50}")
+            print(f"Full LLM response:\n{response}\n{'-'*50}")
         except Exception as e:
             print(f"Error generating LLM response: {e}")
             return f"Error generating response: {str(e)}. Please try again."
@@ -729,10 +773,10 @@ class PersonalizedKazakhAssistant:
         for term, category, definition in unique_terms.values():
             self.tracker.track_word_encounter(user_id, term, definition, category)
 
-        # if unique_terms:
-        #     response += "\n\n📚 **Tracked Bolded Terms**:\n"
-        #     for term, category, definition in sorted(unique_terms.values()):
-        #         response += f"- **{term}** ({category}): {definition}\n"
+        if unique_terms:
+            response += "\n\n📚 **Tracked Bolded Terms**:\n"
+            for term, category, definition in sorted(unique_terms.values()):
+                response += f"- **{term}** ({category}): {definition}\n"
                 
         return response
     
@@ -740,15 +784,15 @@ class PersonalizedKazakhAssistant:
         progress = self.tracker.get_user_progress(user_id)
         
         if progress['total_words'] == 0:
-            return "Сіз әлі үйренуді бастамадыңыз! Маған кез келген қазақ сөзі немесе тіркес туралы сұраңыз. 🌟\n\nYou haven't started learning yet! Ask me about any Kazakh word or idiom to begin your journey. 🌟"
+            return "Сіз әлі үйренуді бастамадыңыз! Маған кез келген қазақ сөзі, тіркес немесе мақал-мәтел туралы сұраңыз. 🌟\n\nYou haven't started learning yet! Ask me about any Kazakh word, idiom, or proverb to begin your journey. 🌟"
         
         report = "📊 **Сіздің үйрену прогресіңіз / Your Learning Progress Report**\n\n"
         
         report += f"🎯 **Үйренген терминдер саны / Total Terms Learned**: {progress['total_words']}\n"
         
         for category, stats in progress['category_stats'].items():
-            emoji = "📝" if category == "word" else "🎭"
-            category_name = "Сөздер / Words" if category == "word" else "Тіркестер / Idioms"
+            emoji = "📝" if category == "word" else "🎭" if category == "idiom" else "📜" if category == "proverb" else "📚"
+            category_name = "Сөздер / Words" if category == "word" else "Тіркестер / Idioms" if category == "idiom" else "Мақал-мәтелдер / Proverbs"
             report += f"{emoji} **{category_name}**: {stats['count']} (Орташа меңгеру / Average mastery: {stats['average_mastery']}/5)\n"
         
         report += f"\n⚡ **Соңғы белсенділік / Recent Activity**: {progress['recent_activity']} терминдер соңғы 7 күнде қаралды / terms reviewed in the last 7 days\n"
@@ -785,7 +829,7 @@ class PersonalizedKazakhAssistant:
         
         response = "📚 **Қайталауға арналған сөздер / Words to Review**:\n\n"
         for word_info in words_to_review:
-            emoji = "📝" if word_info['category'] == "word" else "🎭"
+            emoji = "📝" if word_info['category'] == "word" else "🎭" if word_info['category'] == "idiom" else "📜" if word_info['category'] == "proverb" else "📚"
             mastery_stars = "⭐" * min(word_info['encounter_count'], 5) + "☆" * (5 - min(word_info['encounter_count'], 5))
             response += f"{emoji} **{word_info['word']}** - {mastery_stars} (Кездесу саны / Encounters: {word_info['encounter_count']})\n"
             
@@ -793,7 +837,7 @@ class PersonalizedKazakhAssistant:
             response += f"   {definition_preview}\n\n"
         
         return response
-    
+
     def get_mastered_words(self, user_id: str, page: int = 1, page_size: int = 10) -> str:
         mastered_words = self.tracker.get_mastered_words(user_id, page, page_size)
         
@@ -802,7 +846,7 @@ class PersonalizedKazakhAssistant:
         
         response = f"🏆 **Меңгерілген сөздер / Mastered Words** (Бет / Page: {page}):\n\n"
         for word_info in mastered_words:
-            emoji = "📝" if word_info['category'] == "word" else "🎭"
+            emoji = "📝" if word_info['category'] == "word" else "🎭" if word_info['category'] == "idiom" else "📜" if word_info['category'] == "proverb" else "📚"
             mastery_stars = "🟊" * int(word_info['mastery_level'] * 2) + "⬜" * (10 - int(word_info['mastery_level'] * 2))
             response += f"{emoji} **{word_info['word']}** - {mastery_stars} (Кездесу саны / Encounters: {word_info['encounter_count']})\n"
             
@@ -810,17 +854,16 @@ class PersonalizedKazakhAssistant:
             response += f"   {definition_preview}\n\n"
         
         return response
-    
+
     def get_learning_words(self, user_id: str, page: int = 1, page_size: int = 10) -> str:
         learning_words = self.tracker.get_learning_words(user_id, page, page_size)
         
         if not learning_words:
-            return "Сізде қазір үйрену кезеңінде сөздер жоқ. Жаңа сөздерді немесе тіркестерді сұраңыз! 🌟\n\nYou don't have any words in the learning phase right now. Ask about new words or idioms! 🌟"
+            return "Сізде қазір үйрену кезеңінде сөздер жоқ. Жаңа сөздерді, тіркестерді немесе мақал-мәтелдерді сұраңыз! 🌟\n\nYou don't have any words in the learning phase right now. Ask about new words, idioms, or proverbs! 🌟"
         
         response = f"📖 **Үйрену кезеңіндегі сөздер / Words in Learning** (Бет / Page: {page}):\n\n"
         for word_info in learning_words:
-            emoji = "📝" if word_info['category'] == "word" else "🎭"
-
+            emoji = "📝" if word_info['category'] == "word" else "🎭" if word_info['category'] == "idiom" else "📜" if word_info['category'] == "proverb" else "📚"
             mastery_stars = "⭐" * min(word_info['encounter_count'], 5) + "☆" * (5 - min(word_info['encounter_count'], 5))
             response += f"{emoji} **{word_info['word']}** - {mastery_stars} (Кездесу саны / Encounters: {word_info['encounter_count']})\n"
             
@@ -843,7 +886,7 @@ class PersonalizedKazakhAssistant:
         for term in sorted(self.known_terms):  
             normalized_term = self.normalize_term(term)
             if normalized_term not in shown_words and len(term.split()) == 1:
-                retrieved_docs = self.vectorstore.similarity_search(term, k=5)
+                retrieved_docs = self.vectorstore.similarity_search(term, k=15)
                 for doc in retrieved_docs:
                     lines = doc.page_content.replace('\r\n', '\n').replace('\r', '\n').split('\n')
                     for line in lines:
@@ -873,7 +916,7 @@ class PersonalizedKazakhAssistant:
         for term in sorted(self.known_terms):  
             normalized_term = self.normalize_term(term)
             if normalized_term not in shown_idioms and len(term.split()) > 1:
-                retrieved_docs = self.vectorstore.similarity_search(term, k=5)
+                retrieved_docs = self.vectorstore.similarity_search(term, k=15)
                 for doc in retrieved_docs:
                     lines = doc.page_content.replace('\r\n', '\n').replace('\r', '\n').split('\n')
                     for line in lines:
@@ -1158,6 +1201,772 @@ with gr.Blocks(title="🇰🇿 Kazakh Learning API") as demo:
                 ["Teach me Kazakh verb conjugation in English", "English"]
             ]
         )
+    
+    with gr.Tab("📖 API Documentation"):
+        gr.Markdown("""
+        ## API Endpoints for Flutter Integration
+        ### Base URL: `https://huggingface.co/spaces/GuestUser33/kazakh-learning-api`
+
+        ### Authentication Flow:
+        1. **Login** to get a session token
+        2. **Use session token** for subsequent API calls
+        3. **Session tokens expire** after inactivity
+
+        ### Available Endpoints:
+
+        #### 1. Login API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id"],
+        "fn_index": 0
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "session_token": "uuid-string",
+                    "user_id": "user_id",
+                    "message": "Login successful"
+                }
+            ]
+        }
+        ```
+
+        #### 2. Chat API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["message", "user_id", "session_token", "English"],
+        "fn_index": 1
+        }
+        ```
+        **Parameters**:
+        - `message`: The user's query (e.g., "сәлем деген не?" or "/progress")
+        - `user_id`: Unique identifier for the user
+        - `session_token`: Session token from login (use empty string "" if no token)
+        - `target_language`: Language for responses ("English", "Kazakh", or "Russian")
+
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "response": "response_text",
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 3. Progress API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 2
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "progress_text": "progress_report",
+                    "progress_data": {
+                        "category_stats": {
+                            "word": {"count": number, "average_mastery": number},
+                            "idiom": {"count": number, "average_mastery": number}
+                        },
+                        "recent_activity": number,
+                        "daily_activity": [{"date": "YYYY-MM-DD", "daily_count": number}, ...],
+                        "total_words": number
+                    },
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 4. Recommendations API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 3
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "recommendations_text": "recommendations",
+                    "recommendations_list": ["recommendation1", "recommendation2", ...],
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 5. Review Words API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 4
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "review_text": "review_words",
+                    "review_data": [
+                        {
+                            "word": "word",
+                            "definition": "definition",
+                            "category": "word|idiom",
+                            "mastery_level": number,
+                            "last_reviewed": "YYYY-MM-DDTHH:MM:SS",
+                            "encounter_count": number
+                        },
+                        ...
+                    ],
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 6. Mastered Words API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 5
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "mastered_text": "mastered_words",
+                    "mastered_data": [
+                        {
+                            "word": "word",
+                            "definition": "definition",
+                            "category": "word|idiom",
+                            "mastery_level": number,
+                            "encounter_count": number
+                        },
+                        ...
+                    ],
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 7. New Word API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 6
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "word": "new_word",
+                    "definition": "definition",
+                    "category": "word",
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 8. New Idiom API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token"],
+        "fn_index": 7
+        }
+        ```
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "word": "new_idiom",
+                    "definition": "definition",
+                    "category": "idiom",
+                    "user_id": "user_id"
+                }
+            ]
+        }
+        ```
+
+        #### 9. Learning Words API
+        ```
+        POST /api/predict
+        Content-Type: application/json
+
+        {
+        "data": ["user_id", "session_token", page, page_size],
+        "fn_index": 8
+        }
+        ```
+        **Parameters**:
+        - `user_id`: Unique identifier for the user
+        - `session_token`: Session token from login (use empty string "" if no token)
+        - `page`: Page number for pagination (default: 1)
+        - `page_size`: Number of items per page (default: 10)
+
+        **Response**:
+        ```json
+        {
+            "data": [
+                {
+                    "success": true,
+                    "learning_text": "learning_words",
+                    "learning_data": [
+                        {
+                            "word": "word",
+                            "definition": "definition",
+                            "category": "word|idiom",
+                            "mastery_level": number,
+                            "encounter_count": number
+                        },
+                        ...
+                    ],
+                    "user_id": "user_id",
+                    "page": number,
+                    "page_size": number
+                }
+            ]
+        }
+        ```
+
+        ### Flutter Integration Example:
+        ```dart
+        import 'dart:convert';
+        import 'package:http/http.dart' as http;
+
+        class KazakhLearningAPI {
+            static const String baseUrl = 'https://huggingface.co/spaces/GuestUser33/kazakh-learning-api';
+            String? sessionToken;
+            String? userId;
+
+            // Login and get session token
+            Future<bool> login(String userId) async {
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId],
+                            'fn_index': 0
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            this.userId = userId;
+                            this.sessionToken = result['data'][0]['session_token'];
+                            return true;
+                        }
+                    }
+                } catch (e) {
+                    print('Login error: $e');
+                }
+                return false;
+            }
+
+            // Send chat message
+            Future<String?> sendMessage(String message, {String targetLanguage = 'English'}) async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [message, userId, sessionToken ?? "", targetLanguage],
+                            'fn_index': 1
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0]['response'];
+                        }
+                    }
+                } catch (e) {
+                    print('Send message error: $e');
+                }
+                return null;
+            }
+
+            // Get user progress
+            Future<Map?> getProgress() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 2
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0]['progress_data'];
+                        }
+                    }
+                } catch (e) {
+                    print('Get progress error: $e');
+                }
+                return null;
+            }
+
+            // Get recommendations
+            Future<List?> getRecommendations() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 3
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return List.from(result['data'][0]['recommendations_list'] ?? []);
+                        }
+                    }
+                } catch (e) {
+                    print('Get recommendations error: $e');
+                }
+                return null;
+            }
+
+            // Get words to review
+            Future<List?> getReviewWords() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 4
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0]['review_data'];
+                        }
+                    }
+                } catch (e) {
+                    print('Get review words error: $e');
+                }
+                return null;
+            }
+
+            // Get mastered words
+            Future<List?> getMasteredWords() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 5
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0]['mastered_data'];
+                        }
+                    }
+                } catch (e) {
+                    print('Get mastered words error: $e');
+                }
+                return null;
+            }
+
+            // Get new word
+            Future<Map?> getNewWord() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 6
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0];
+                        }
+                    }
+                } catch (e) {
+                    print('Get new word error: $e');
+                }
+                return null;
+            }
+
+            // Get new idiom
+            Future<Map?> getNewIdiom() async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? ""],
+                            'fn_index': 7
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0];
+                        }
+                    }
+                } catch (e) {
+                    print('Get new idiom error: $e');
+                }
+                return null;
+            }
+
+            // Get learning words
+            Future<Map?> getLearningWords({int page = 1, int pageSize = 10}) async {
+                if (userId == null) return null;
+
+                try {
+                    final response = await http.post(
+                        Uri.parse('$baseUrl/api/predict'),
+                        headers: {'Content-Type': 'application/json'},
+                        body: jsonEncode({
+                            'data': [userId, sessionToken ?? "", page, pageSize],
+                            'fn_index': 8
+                        }),
+                    );
+
+                    if (response.statusCode == 200) {
+                        final result = jsonDecode(response.body);
+                        if (result['data'] != null && result['data'][0]['success'] == true) {
+                            return result['data'][0];
+                        }
+                    }
+                } catch (e) {
+                    print('Get learning words error: $e');
+                }
+                return null;
+            }
+
+            // Helper method to check if session is valid
+            bool get isLoggedIn => userId != null;
+
+            // Logout method
+            void logout() {
+                userId = null;
+                sessionToken = null;
+            }
+        }
+        ```
+
+        ### Key Features:
+        - ✅ **Multi-User Support**: Each user has separate learning progress
+        - ✅ **Session Management**: Secure session tokens for authentication
+        - ✅ **Personalized Tracking**: Individual progress tracking per user using RAG model
+        - ✅ **Multi-Language Support**: Responses in English, Kazakh, or Russian
+        - ✅ **API Ready**: All endpoints ready for mobile app integration
+        - ✅ **Session Validation**: Automatic session validation and expiry
+
+        ### Usage Notes:
+        - Always call **login** first to get a session token
+        - Use **empty string ""** for session_token if no token is available
+        - Specify `target_language` ("English", "Kazakh", "Russian") for responses
+        - Handle **session expiry** by re-logging in
+        - Use **unique user_id** for each user (e.g., email, username)
+        - Commands like `/progress`, `/recommendations`, `/review`, `/mastered`, `/newword`, `/newidiom`, `/learning`, `/help` are supported
+        - **Error handling** is crucial - always check for success field and handle exceptions
+
+        ### Error Handling:
+        All API responses include a `success` field. If `success: false`, check the `error` field for details:
+        ```json
+        {
+            "data": [
+                {
+                    "success": false,
+                    "error": "Error message here"
+                }
+            ]
+        }
+        """
+        )
+    
+    with gr.Tab("🔌 API Testing"):
+        gr.Markdown("## Test API Endpoints")
+        gr.Markdown("### Use these endpoints programmatically:")
+        gr.Markdown("""
+        **API Endpoints:**
+        - **Login:** `/api/predict` with `fn_index=0`
+        - **Chat:** `/api/predict` with `fn_index=1`
+        - **Progress:** `/api/predict` with `fn_index=2`
+        - **Recommendations:** `/api/predict` with `fn_index=3`
+        - **Review Words:** `/api/predict` with `fn_index=4`
+        - **Mastered Words:** `/api/predict` with `fn_index=5`
+        - **New Word:** `/api/predict` with `fn_index=6`
+        - **New Idiom:** `/api/predict` with `fn_index=7`
+        - **Learning Words:** `/api/predict` with `fn_index=8`
+        """)
+
+        with gr.Row():
+            with gr.Column():
+                user_id_input = gr.Textbox(label="User ID", value="test_user", placeholder="Enter unique user ID")
+                session_token_input = gr.Textbox(label="Session Token", placeholder="Session token (get from login)")
+                message_input = gr.Textbox(label="Message", placeholder="Enter your message in Kazakh or English")
+                target_language_api = gr.Dropdown(label="Explanation Language", choices=["English", "Kazakh", "Russian"], value="English")
+                page_input = gr.Number(label="Page Number", value=1, minimum=1, precision=0)
+                page_size_input = gr.Number(label="Page Size", value=10, minimum=1, precision=0)
+
+        with gr.Row():
+            login_btn = gr.Button("🔑 Test Login API")
+            chat_btn = gr.Button("💬 Test Chat API")
+            progress_btn = gr.Button("📊 Test Progress API")
+            recommendations_btn = gr.Button("💡 Test Recommendations API")
+            review_btn = gr.Button("📚 Test Review Words API")
+            mastered_btn = gr.Button("🏆 Test Mastered Words API")
+            new_word_btn = gr.Button("📝 Test New Word API")
+            new_idiom_btn = gr.Button("🎭 Test New Idiom API")
+            learning_btn = gr.Button("📖 Test Learning Words API")
+
+        api_output = gr.JSON(label="API Response")
+
+        login_interface = gr.Interface(
+            fn=api_login,
+            inputs=gr.Textbox(label="User ID"),
+            outputs=gr.JSON(label="Response"),
+            title="Login API",
+            description="Login endpoint",
+            allow_flagging="never"
+        )
+
+        chat_api_interface = gr.Interface(
+            fn=api_chat,
+            inputs=[
+                gr.Textbox(label="Message"),
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token"),
+                gr.Dropdown(label="Target Language", choices=["English", "Kazakh", "Russian"])
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Chat API",
+            description="Chat endpoint",
+            allow_flagging="never"
+        )
+
+        progress_interface = gr.Interface(
+            fn=api_progress,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Progress API",
+            description="Progress endpoint",
+            allow_flagging="never"
+        )
+
+        recommendations_interface = gr.Interface(
+            fn=api_recommendations,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Recommendations API",
+            description="Recommendations endpoint",
+            allow_flagging="never"
+        )
+
+        review_interface = gr.Interface(
+            fn=api_review_words,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Review Words API",
+            description="Review words endpoint",
+            allow_flagging="never"
+        )
+
+        mastered_interface = gr.Interface(
+            fn=api_mastered_words,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Mastered Words API",
+            description="Mastered words endpoint",
+            allow_flagging="never"
+        )
+
+        new_word_interface = gr.Interface(
+            fn=api_new_word,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="New Word API",
+            description="New word endpoint",
+            allow_flagging="never"
+        )
+
+        new_idiom_interface = gr.Interface(
+            fn=api_new_idiom,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="New Idiom API",
+            description="New idiom endpoint",
+            allow_flagging="never"
+        )
+
+        learning_interface = gr.Interface(
+            fn=api_learning_words,
+            inputs=[
+                gr.Textbox(label="User ID"),
+                gr.Textbox(label="Session Token"),
+                gr.Number(label="Page Number"),
+                gr.Number(label="Page Size")
+            ],
+            outputs=gr.JSON(label="Response"),
+            title="Learning Words API",
+            description="Learning words endpoint",
+            allow_flagging="never"
+        )
+
+        login_btn.click(
+            fn=api_login,
+            inputs=user_id_input,
+            outputs=api_output
+        )
+
+        chat_btn.click(
+            fn=api_chat,
+            inputs=[message_input, user_id_input, session_token_input, target_language_api],
+            outputs=api_output
+        )
+
+        progress_btn.click(
+            fn=api_progress,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        recommendations_btn.click(
+            fn=api_recommendations,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        review_btn.click(
+            fn=api_review_words,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        mastered_btn.click(
+            fn=api_mastered_words,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        new_word_btn.click(
+            fn=api_new_word,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        new_idiom_btn.click(
+            fn=api_new_idiom,
+            inputs=[user_id_input, session_token_input],
+            outputs=api_output
+        )
+
+        learning_btn.click(
+            fn=api_learning_words,
+            inputs=[user_id_input, session_token_input, page_input, page_size_input],
+            outputs=api_output
+        )
 
 if __name__ == "__main__":
     demo.launch(