v1.8.3: добавлены docstrings и комментарии по AGENTS.md ко всем ключевым файлам

max_bot/app/yandex_gpt.py

@@ -1,3 +1,9 @@
+"""
+YandexGPT интеграция для анализа намерений и генерации ответов.
+
+Модель: yandexgpt-lite
+API: https://llm.api.cloud.yandex.net/foundationModels/v1/completion
+"""
 import httpx
 import json
 import logging
@@ -14,6 +20,7 @@ YANDEX_GPT_MODEL = "yandexgpt-lite"
 
 
 class YandexGPT:
+    """Клиент YandexGPT для анализа намерений и генерации ответов."""
     def __init__(self):
         self._api_key: Optional[str] = None
         self._folder_id: Optional[str] = None
@@ -27,6 +34,7 @@ class YandexGPT:
         return await self._load_credentials()
 
     async def _request(self, prompt: str, system_prompt: str = "", temperature: float = 0.3, max_tokens: int = 1000) -> Optional[str]:
+        """Базовый запрос к YandexGPT API."""
         if not await self._load_credentials():
             return None
 
@@ -65,11 +73,13 @@ class YandexGPT:
             return None
 
     def _sanitize_input(self, text: str) -> str:
+        """Очистка и обрезка входного текста (макс. 2000 символов)."""
         text = text[:MAX_INPUT_LENGTH]
         text = text.replace("\r\n", "\n").replace("\r", "\n")
         return text
 
     async def analyze_intent(self, text: str, history_context: str = "") -> str:
+        """Анализ намерения: ticket/question/unknown. Aggressive ticket detection для услуг."""
         safe_text = self._sanitize_input(text)
         safe_history = self._sanitize_input(history_context) if history_context else ""
         system_prompt = (
@@ -97,6 +107,7 @@ class YandexGPT:
         return "unknown"
 
     async def generate_answer(self, question: str, context: str, history_context: str = "") -> Optional[str]:
+        """Генерация ответа на вопрос с контекстом из базы знаний."""
         safe_question = self._sanitize_input(question)
         safe_history = self._sanitize_input(history_context) if history_context else ""
         system_prompt = (
@@ -116,6 +127,7 @@ class YandexGPT:
         return await self._request(user_prompt, system_prompt)
 
     async def clarify_intent(self, text: str, history_context: str = "") -> str:
+        """Уточнение намерения: если есть слова-маркеры — отвечает без 'уточните'."""
         safe_text = self._sanitize_input(text)
         safe_history = self._sanitize_input(history_context) if history_context else ""
         system_prompt = (
@@ -159,6 +171,7 @@ class YandexGPT:
         return result or "Подскажите, чем я могу помочь? Вы хотите задать вопрос об услугах AegisOne или оставить заявку?"
 
     async def generate_kb_card(self, user_questions: list) -> Optional[dict]:
+        """Генерация карточки базы знаний из вопросов пользователей (JSON)."""
         joined = "\n".join(f"- {q}" for q in user_questions)
         system_prompt = (
             "Ты — редактор базы знаний компании AegisOne Engineering. "