add

README.md

@@ -1,17 +1,17 @@
 ---
-title: Log Compiler App
+title: Анализатор логов
 emoji: 🧠
 colorFrom: blue
 colorTo: green
 sdk: gradio
-sdk_version: "4.44.0"
+sdk_version: "4.44.1"
 app_file: app.py
 pinned: false
 ---
 
-# Log Compiler App
+# Анализатор логов
 
-Gradio демо: вставляете логи/стектрейс, получаете тип инцидента, человеческое объяснение, вероятную причину, проверки и локальные ранбуки. Пайплайн использует трансформеры: zero-shot classifier, summarizer, sentence-embedding retriever (опционально reranker и NLI).
+Gradio‑демо: вставляете логи/стектрейс, получаете тип инцидента, человеческое объяснение, вероятную причину, набор проверок и локальные ранбуки. Пайплайн использует трансформеры (zero-shot классификатор, summarizer, sentence-embedding retriever, при желании reranker и NLI).
 
 ## Установка локально
 
@@ -25,7 +25,13 @@ pip install -r requirements.txt
 python app.py
 ```
 
-Если localhost недоступен (WSL/прокси), по умолчанию включён share-линк; управлять можно `GRADIO_SHARE=0/1`. `server_name=0.0.0.0` выставлен.
+По умолчанию приложение слушает `127.0.0.1:7860` без публичного шаринга. Чтобы открыть интерфейс наружу, задайте:
+
+```bash
+GRADIO_HOST=0.0.0.0 GRADIO_SHARE=1 python app.py
+```
+
+или выставьте нужный `GRADIO_SERVER_NAME` / `PORT`.
 
 ## Запуск на Hugging Face Spaces
 
@@ -35,15 +41,15 @@ python app.py
 
 ## Использование
 
-- Вставьте логи/стектрейс, выберите source (auto/python/java/node/k8s).
-- Опции: retrieval (локальный KB `kb/`), NLI-проверка гипотез, slider verbosity.
-- Нажмите **Analyze**, вкладки покажут Incident, Explanation, Cause+Checks, Retrieval, Verification, Ticket template. Есть Export JSON.
+- Вставьте логи/стектрейс, выберите источник (auto/python/java/node/k8s).
+- Опции: поиск по локальной базе (`kb/`), NLI-проверка гипотез, слайдер детализации объяснения.
+- Нажмите **Анализировать**: вкладки покажут тип инцидента, пояснение, причину/проверки, найденные ранбуки, проверку гипотез и шаблон тикета. Можно выгрузить JSON.
 
 ## Примеры
 
 - `samples/sample_python.txt` — HTTP timeout.
-- `samples/sample_k8s.txt` — CrashLoop/OOMKilled pod.
-- `samples/sample_java.txt` — NullPointerException auth failure.
+- `samples/sample_k8s.txt` — под с CrashLoop/OOMKilled.
+- `samples/sample_java.txt` — NullPointerException из-за auth failure.
 
 ## Состав
 

app.py

@@ -9,25 +9,107 @@ from pipeline import IncidentPipeline, IncidentResult, serialize_result
 from preprocess import truncate_logs
 
 
+class DownloadOnlyFile(gr.File):
+    """Файл только для скачивания, скрытый из OpenAPI-схемы Gradio."""
+
+    is_template = True
+
+    @property
+    def skip_api(self) -> bool:
+        return True
+
+
 pipeline = IncidentPipeline()
 
 
+LABEL_DISPLAY = {
+    "oom": "Переполнение памяти (OOM)",
+    "timeout": "Таймаут",
+    "auth_failure": "Ошибка аутентификации/авторизации",
+    "db_connection": "Сбой подключения к базе данных",
+    "dns_resolution": "Ошибка DNS",
+    "tls_handshake": "Ошибка TLS-рукопожатия",
+    "crashloop": "CrashLoop / повторные рестарты",
+    "null_pointer": "NullPointer / None reference",
+    "resource_exhaustion": "Исчерпание ресурсов",
+    "network_partition": "Сетевая изоляция",
+}
+
+SOURCE_DISPLAY = {
+    "python": "Python",
+    "java": "Java",
+    "node": "Node.js",
+    "k8s": "Kubernetes",
+    "auto": "Auto",
+}
+
+SIGNATURE_DISPLAY = {
+    "stacktrace": "стектрейс",
+    "timestamps": "таймстемпы",
+    "log_levels": "уровни логов",
+    "k8s": "ошибки Kubernetes",
+    "oom": "признаки OOM",
+    "timeout": "упоминания таймаута",
+}
+
+SPEC_SUFFIX = "_specific"
+
+
+def human_label(label: str) -> str:
+    """
+    Возвращает человеко-понятное название категории инцидента.
+    """
+    if label.endswith(SPEC_SUFFIX):
+        base = label[: -len(SPEC_SUFFIX)]
+        source_name = SOURCE_DISPLAY.get(base, base)
+        return f"Категория, специфичная для {source_name}"
+    return LABEL_DISPLAY.get(label, label)
+
+
+def human_signature(sig: str) -> str:
+    """
+    Конвертирует машинную сигнатуру в более дружелюбный текст.
+    """
+    return SIGNATURE_DISPLAY.get(sig, sig)
+
+
+def env_flag(name: str, default: bool = False) -> bool:
+    """
+    Безопасно читает булевы переменные окружения (1/0, true/false и т.д.).
+    """
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.lower() in ("1", "true", "yes", "on")
+
+
 def format_incident_section(result: IncidentResult) -> str:
-    alt_text = ", ".join(f"{a['label']} ({a['score']:.2f})" for a in result.incident_alternatives)
-    sigs = ", ".join(result.signatures) if result.signatures else "none"
+    """
+    Формирует markdown-блок с типом инцидента, альтернативами и сигнатурами.
+    """
+    alt_text = ", ".join(
+        f"{human_label(a['label'])} ({a['score']:.2f})" for a in result.incident_alternatives
+    )
+    sigs = ", ".join(human_signature(sig) for sig in result.signatures) if result.signatures else "нет"
     return (
-        f"**Incident:** {result.incident_label} (confidence {result.incident_score:.2f})\n\n"
-        f"**Top alternatives:** {alt_text if alt_text else 'n/a'}\n\n"
-        f"**Detected signatures:** {sigs}"
+        f"**Инцидент:** {human_label(result.incident_label)} (уверенность {result.incident_score:.2f})\n\n"
+        f"**Альтернативы:** {alt_text if alt_text else 'н/д'}\n\n"
+        f"**Обнаруженные сигнатуры:** {sigs}"
     )
 
 
 def format_cause_section(result: IncidentResult) -> str:
+    """
+    Создаёт markdown с причиной и списком проверок.
+    """
     checks_md = "\n".join([f"- {c}" for c in result.checks])
-    return f"**Likely cause:** {result.likely_cause}\n\n**Checks / next steps:**\n{checks_md}"
+    return f"**Вероятная причина:** {result.likely_cause}\n\n**Проверки / следующие шаги:**\n{checks_md}"
 
 
 def analyze_logs(logs: str, source: str, use_retrieval: bool, use_nli: bool, verbosity: int):
+    """
+    Основная функция кнопки «Анализировать»: прогоняет пайплайн и возвращает выводы.
+    """
     try:
         res = pipeline.process(
             logs,
@@ -37,7 +119,7 @@ def analyze_logs(logs: str, source: str, use_retrieval: bool, use_nli: bool, ver
             verbosity=verbosity,
         )
     except Exception as exc:
-        message = f"Error: {exc}"
+        message = f"Ошибка: {exc}"
         empty_table: List[List[Any]] = []
         return (
             message,
@@ -46,7 +128,7 @@ def analyze_logs(logs: str, source: str, use_retrieval: bool, use_nli: bool, ver
             empty_table,
             empty_table,
             None,
-            f"Failed: {exc}",
+            f"Сбой: {exc}",
         )
 
     retrieval_rows = [
@@ -64,33 +146,39 @@ def analyze_logs(logs: str, source: str, use_retrieval: bool, use_nli: bool, ver
         retrieval_rows,
         verification_rows,
         state_payload,
-        "Analysis completed.",
+        "Анализ завершён.",
     )
 
 
 def ticket_template(state: Optional[str], logs: str) -> str:
+    """
+    Собирает черновик тикета опираясь на результаты последнего анализа.
+    """
     if not state:
-        return "Run analysis first."
+        return "Сначала запустите анализ."
     try:
         parsed = json.loads(state) if isinstance(state, str) else state
     except Exception:
-        return "State corrupted. Re-run analysis."
+        return "Состояние повреждено. Повторите анализ."
     clipped_logs = truncate_logs(logs, head_lines=30, tail_lines=10, max_lines=60)
     checks = parsed.get("checks") or []
     checks_md = "\n".join(f"- {c}" for c in checks)
-    summary = f"{parsed.get('incident_label','?')} — {parsed.get('explanation','')[:180]}"
+    summary = f"{human_label(parsed.get('incident_label','?'))} — {parsed.get('explanation','')[:180]}"
     template = (
-        f"Summary:\n{summary}\n\n"
-        f"Steps to reproduce:\n- Describe sequence leading to error (fill in).\n- Attach failing request/sample data.\n\n"
-        f"Expected:\n- Service handles request successfully.\n\n"
-        f"Actual:\n- {parsed.get('likely_cause','')}\n\n"
-        f"Checks performed / next steps:\n{checks_md}\n\n"
-        f"Logs snippet:\n{clipped_logs}\n"
+        f"Сводка:\n{summary}\n\n"
+        f"Шаги для воспроизведения:\n- Опишите последовательность, которая привела к сбою.\n- Приложите проблемный запрос или данные.\n\n"
+        f"Ожидаемый результат:\n- Сервис успешно обрабатывает запрос.\n\n"
+        f"Фактический результат:\n- {parsed.get('likely_cause','')}\n\n"
+        f"Проверки / дальнейшие шаги:\n{checks_md}\n\n"
+        f"Фрагмент логов:\n{clipped_logs}\n"
     )
     return template
 
 
 def export_json(state: Optional[str]):
+    """
+    Сохраняет результат анализа во временный JSON и возвращает путь до него.
+    """
     if not state:
         return None
     # If state is dict, dump; if already JSON string, use as-is.
@@ -102,47 +190,47 @@ def export_json(state: Optional[str]):
     return tmp.name
 
 
-with gr.Blocks(title="Log Compiler App") as demo:
-    gr.Markdown("# Log Compiler App\nPaste logs/stacktrace to get incident classification, explanations, and runbook suggestions.")
-    # Hidden textbox to store serialized state; avoids schema issues in HF Spaces.
+with gr.Blocks(title="Анализатор логов") as demo:
+    gr.Markdown("# Анализатор логов\nВставьте логи/стектрейс и получите тип инцидента, объяснения и подсказки по расследованию.")
+    # Скрытое поле для сериализованного состояния.
     state_box = gr.Textbox(visible=False, show_label=False)
 
     with gr.Row():
-        with gr.Column(scale=1):
-            logs_input = gr.Textbox(lines=20, label="Logs / Stacktrace", placeholder="Paste logs here...")
+        with gr.Column(scale=5):
+            logs_input = gr.Textbox(lines=20, label="Логи / стек", placeholder="Вставьте логи сюда...")
             source_dropdown = gr.Dropdown(
                 ["auto", "python", "java", "node", "k8s"],
                 value="auto",
-                label="Source",
+                label="Источник",
             )
-            use_retrieval = gr.Checkbox(value=True, label="Use retrieval (local KB)")
-            use_nli = gr.Checkbox(value=False, label="Verify hypothesis (NLI)")
-            verbosity_slider = gr.Slider(0, 2, value=1, step=1, label="Verbosity")
-            analyze_btn = gr.Button("Analyze")
-            ticket_btn = gr.Button("Generate ticket template")
-            export_btn = gr.Button("Export JSON")
-            json_output = gr.File(label="JSON export")
-            status = gr.Markdown("Ready.")
-        with gr.Column(scale=1.2):
-            with gr.Tab("Incident Type"):
+            use_retrieval = gr.Checkbox(value=True, label="Использовать поиск по базе знаний")
+            use_nli = gr.Checkbox(value=False, label="Проверять гипотезы (NLI)")
+            verbosity_slider = gr.Slider(0, 2, value=1, step=1, label="Детализация объяснения")
+            analyze_btn = gr.Button("Анализировать")
+            ticket_btn = gr.Button("Сформировать шаблон тикета")
+            export_btn = gr.Button("Экспорт JSON")
+            json_output = DownloadOnlyFile(label="Экспорт JSON")
+            status = gr.Markdown("Готово.")
+        with gr.Column(scale=6):
+            with gr.Tab("Тип инцидента"):
                 incident_md = gr.Markdown()
-            with gr.Tab("Human Explanation"):
+            with gr.Tab("Пояснение"):
                 explanation_md = gr.Markdown()
-            with gr.Tab("Likely Cause + Checks"):
+            with gr.Tab("Причина и проверки"):
                 cause_md = gr.Markdown()
-            with gr.Tab("Retrieved Runbooks"):
+            with gr.Tab("Найденные ранбуки"):
                 retrieval_df = gr.Dataframe(
-                    headers=["Title", "Score", "Path", "Excerpt"],
+                    headers=["Название", "Сходство", "Путь", "Фрагмент"],
                     datatype=["str", "number", "str", "str"],
                     interactive=False,
                 )
-            with gr.Tab("Verification"):
+            with gr.Tab("Проверка гипотез"):
                 verification_df = gr.Dataframe(
-                    headers=["Hypothesis", "Label", "Score"],
+                    headers=["Гипотеза", "Метка", "Счёт"],
                     datatype=["str", "str", "number"],
                     interactive=False,
                 )
-            with gr.Tab("Ticket Template"):
+            with gr.Tab("Шаблон тикета"):
                 ticket_md = gr.Markdown()
 
     analyze_btn.click(
@@ -165,6 +253,13 @@ with gr.Blocks(title="Log Compiler App") as demo:
 
 
 if __name__ == "__main__":
-    share_env = os.getenv("GRADIO_SHARE")
     in_hf_space = bool(os.getenv("SPACE_ID") or os.getenv("HF_SPACE"))
-    demo.launch(server_name="0.0.0.0", share=False)
+    share_flag = False if in_hf_space else env_flag("GRADIO_SHARE", default=False)
+    host = os.getenv("GRADIO_HOST") or os.getenv("GRADIO_SERVER_NAME") or "127.0.0.1"
+    port = int(os.getenv("PORT") or os.getenv("GRADIO_SERVER_PORT") or 7860)
+    demo.queue(api_open=False).launch(
+        server_name=host,
+        server_port=port,
+        share=share_flag,
+        show_api=False,
+    )

app.pyi

@@ -0,0 +1,246 @@
+import json
+import os
+import tempfile
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+
+from pipeline import IncidentPipeline, IncidentResult, serialize_result
+from preprocess import truncate_logs
+
+from gradio.events import Dependency
+
+class DownloadOnlyFile(gr.File):
+    """Файл только для скачивания, скрытый из OpenAPI-схемы Gradio."""
+
+    is_template = True
+
+    @property
+    def skip_api(self) -> bool:
+        return True
+    from typing import Callable, Literal, Sequence, Any, TYPE_CHECKING
+    from gradio.blocks import Block
+    if TYPE_CHECKING:
+        from gradio.components import Timer
+
+
+pipeline = IncidentPipeline()
+
+
+LABEL_DISPLAY = {
+    "oom": "Переполнение памяти (OOM)",
+    "timeout": "Таймаут",
+    "auth_failure": "Ошибка аутентификации/авторизации",
+    "db_connection": "Сбой подключения к базе данных",
+    "dns_resolution": "Ошибка DNS",
+    "tls_handshake": "Ошибка TLS-рукопожатия",
+    "crashloop": "CrashLoop / повторные рестарты",
+    "null_pointer": "NullPointer / None reference",
+    "resource_exhaustion": "Исчерпание ресурсов",
+    "network_partition": "Сетевая изоляция",
+}
+
+SOURCE_DISPLAY = {
+    "python": "Python",
+    "java": "Java",
+    "node": "Node.js",
+    "k8s": "Kubernetes",
+    "auto": "Auto",
+}
+
+SIGNATURE_DISPLAY = {
+    "stacktrace": "стектрейс",
+    "timestamps": "таймстемпы",
+    "log_levels": "уровни логов",
+    "k8s": "ошибки Kubernetes",
+    "oom": "признаки OOM",
+    "timeout": "упоминания таймаута",
+}
+
+SPEC_SUFFIX = "_specific"
+
+
+def human_label(label: str) -> str:
+    if label.endswith(SPEC_SUFFIX):
+        base = label[: -len(SPEC_SUFFIX)]
+        source_name = SOURCE_DISPLAY.get(base, base)
+        return f"Категория, специфичная для {source_name}"
+    return LABEL_DISPLAY.get(label, label)
+
+
+def human_signature(sig: str) -> str:
+    return SIGNATURE_DISPLAY.get(sig, sig)
+
+
+def env_flag(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.lower() in ("1", "true", "yes", "on")
+
+
+def format_incident_section(result: IncidentResult) -> str:
+    alt_text = ", ".join(
+        f"{human_label(a['label'])} ({a['score']:.2f})" for a in result.incident_alternatives
+    )
+    sigs = ", ".join(human_signature(sig) for sig in result.signatures) if result.signatures else "нет"
+    return (
+        f"**Инцидент:** {human_label(result.incident_label)} (уверенность {result.incident_score:.2f})\n\n"
+        f"**Альтернативы:** {alt_text if alt_text else 'н/д'}\n\n"
+        f"**Обнаруженные сигнатуры:** {sigs}"
+    )
+
+
+def format_cause_section(result: IncidentResult) -> str:
+    checks_md = "\n".join([f"- {c}" for c in result.checks])
+    return f"**Вероятная причина:** {result.likely_cause}\n\n**Проверки / следующие шаги:**\n{checks_md}"
+
+
+def analyze_logs(logs: str, source: str, use_retrieval: bool, use_nli: bool, verbosity: int):
+    try:
+        res = pipeline.process(
+            logs,
+            source=source,
+            use_retrieval=use_retrieval,
+            use_nli=use_nli,
+            verbosity=verbosity,
+        )
+    except Exception as exc:
+        message = f"Ошибка: {exc}"
+        empty_table: List[List[Any]] = []
+        return (
+            message,
+            "",
+            "",
+            empty_table,
+            empty_table,
+            None,
+            f"Сбой: {exc}",
+        )
+
+    retrieval_rows = [
+        [r["title"], round(r["score"], 3), r["path"], r["excerpt"]]
+        for r in res.retrieved
+    ]
+    verification_rows = [
+        [v["hypothesis"], v["label"], round(v["score"], 3)] for v in res.verification
+    ]
+    state_payload = serialize_result(res)
+    return (
+        format_incident_section(res),
+        res.explanation,
+        format_cause_section(res),
+        retrieval_rows,
+        verification_rows,
+        state_payload,
+        "Анализ завершён.",
+    )
+
+
+def ticket_template(state: Optional[str], logs: str) -> str:
+    if not state:
+        return "Сначала запустите анализ."
+    try:
+        parsed = json.loads(state) if isinstance(state, str) else state
+    except Exception:
+        return "Состояние повреждено. Повторите анализ."
+    clipped_logs = truncate_logs(logs, head_lines=30, tail_lines=10, max_lines=60)
+    checks = parsed.get("checks") or []
+    checks_md = "\n".join(f"- {c}" for c in checks)
+    summary = f"{human_label(parsed.get('incident_label','?'))} — {parsed.get('explanation','')[:180]}"
+    template = (
+        f"Сводка:\n{summary}\n\n"
+        f"Шаги для воспроизведения:\n- Опишите последовательность, которая привела к сбою.\n- Приложите проблемный запрос или данные.\n\n"
+        f"Ожидаемый результат:\n- Сервис успешно обрабатывает запрос.\n\n"
+        f"Фактический результат:\n- {parsed.get('likely_cause','')}\n\n"
+        f"Проверки / дальнейшие шаги:\n{checks_md}\n\n"
+        f"Фрагмент логов:\n{clipped_logs}\n"
+    )
+    return template
+
+
+def export_json(state: Optional[str]):
+    if not state:
+        return None
+    # If state is dict, dump; if already JSON string, use as-is.
+    data = json.dumps(state, ensure_ascii=False, indent=2) if isinstance(state, dict) else state
+    tmp = tempfile.NamedTemporaryFile("w", delete=False, suffix=".json", encoding="utf-8")
+    tmp.write(data)
+    tmp.flush()
+    tmp.close()
+    return tmp.name
+
+
+with gr.Blocks(title="Анализатор логов") as demo:
+    gr.Markdown("# Анализатор логов\nВставьте логи/стектрейс и получите тип инцидента, объяснения и подсказки по расследованию.")
+    # Скрытое поле для сериализованного состояния.
+    state_box = gr.Textbox(visible=False, show_label=False)
+
+    with gr.Row():
+        with gr.Column(scale=5):
+            logs_input = gr.Textbox(lines=20, label="Логи / стек", placeholder="Вставьте логи сюда...")
+            source_dropdown = gr.Dropdown(
+                ["auto", "python", "java", "node", "k8s"],
+                value="auto",
+                label="Источник",
+            )
+            use_retrieval = gr.Checkbox(value=True, label="Использовать поиск по базе знаний")
+            use_nli = gr.Checkbox(value=False, label="Проверять гипотезы (NLI)")
+            verbosity_slider = gr.Slider(0, 2, value=1, step=1, label="Детализация объяснения")
+            analyze_btn = gr.Button("Анализировать")
+            ticket_btn = gr.Button("Сформировать шаблон тикета")
+            export_btn = gr.Button("Экспорт JSON")
+            json_output = DownloadOnlyFile(label="Экспорт JSON")
+            status = gr.Markdown("Готово.")
+        with gr.Column(scale=6):
+            with gr.Tab("Тип инцидента"):
+                incident_md = gr.Markdown()
+            with gr.Tab("Пояснение"):
+                explanation_md = gr.Markdown()
+            with gr.Tab("Причина и проверки"):
+                cause_md = gr.Markdown()
+            with gr.Tab("Найденные ранбуки"):
+                retrieval_df = gr.Dataframe(
+                    headers=["Название", "Сходство", "Путь", "Фрагмент"],
+                    datatype=["str", "number", "str", "str"],
+                    interactive=False,
+                )
+            with gr.Tab("Проверка гипотез"):
+                verification_df = gr.Dataframe(
+                    headers=["Гипотеза", "Метка", "Счёт"],
+                    datatype=["str", "str", "number"],
+                    interactive=False,
+                )
+            with gr.Tab("Шаблон тикета"):
+                ticket_md = gr.Markdown()
+
+    analyze_btn.click(
+        fn=analyze_logs,
+        inputs=[logs_input, source_dropdown, use_retrieval, use_nli, verbosity_slider],
+        outputs=[incident_md, explanation_md, cause_md, retrieval_df, verification_df, state_box, status],
+    )
+
+    ticket_btn.click(
+        fn=ticket_template,
+        inputs=[state_box, logs_input],
+        outputs=ticket_md,
+    )
+
+    export_btn.click(
+        fn=export_json,
+        inputs=state_box,
+        outputs=json_output,
+    )
+
+
+if __name__ == "__main__":
+    in_hf_space = bool(os.getenv("SPACE_ID") or os.getenv("HF_SPACE"))
+    share_flag = False if in_hf_space else env_flag("GRADIO_SHARE", default=False)
+    host = os.getenv("GRADIO_HOST") or os.getenv("GRADIO_SERVER_NAME") or "127.0.0.1"
+    port = int(os.getenv("PORT") or os.getenv("GRADIO_SERVER_PORT") or 7860)
+    demo.queue(api_open=False).launch(
+        server_name=host,
+        server_port=port,
+        share=share_flag,
+        show_api=False,
+    )

pipeline.py

@@ -28,6 +28,9 @@ CANDIDATE_LABELS = [
 
 @dataclass
 class IncidentResult:
+    """
+    Контейнер с результатом пайплайна по одному запуску.
+    """
     incident_label: str
     incident_score: float
     incident_alternatives: List[Dict]
@@ -40,7 +43,13 @@ class IncidentResult:
 
 
 class ModelStore:
+    """
+    Хранит и переиспользует все необходимые ML-пайплайны.
+    """
     def __init__(self):
+        """
+        Загружает и кэширует все необходимые трансформерные пайплайны.
+        """
         self.classifier = pipeline(
             "zero-shot-classification",
             model="facebook/bart-large-mnli",
@@ -59,11 +68,20 @@ class ModelStore:
 
 
 class IncidentPipeline:
+    """
+    Компонуёт все стадии анализа логов в единый процесс.
+    """
     def __init__(self):
+        """
+        Собирает модели и ретривер, готовые к переиспользованию.
+        """
         self.models = ModelStore()
         self.retriever = RunbookRetriever()
 
     def classify(self, text: str, source: str) -> Dict:
+        """
+        Определяет тип инцидента zero-shot классификатором.
+        """
         labels = list(CANDIDATE_LABELS)
         if source and source != "auto":
             labels.append(f"{source}_specific")
@@ -77,6 +95,9 @@ class IncidentPipeline:
         return {"label": label, "score": score, "alternatives": alternatives}
 
     def explain(self, text: str, verbosity: int = 1) -> str:
+        """
+        Делает сжатое пояснение к логам при помощи summarizer.
+        """
         max_len = 180 + 60 * verbosity
         min_len = 40 + 20 * verbosity
         summary = self.models.summarizer(
@@ -90,78 +111,85 @@ class IncidentPipeline:
     def generate_cause_and_checks(
         self, result: PreprocessResult, label: str, retrieved: List[Dict]
     ) -> tuple[str, List[str]]:
+        """
+        Подбирает человеко-понятную причину и список проверок по категории.
+        """
         cause_map = {
-            "oom": "Service likely exhausted memory and was terminated.",
-            "crashloop": "Container keeps restarting due to repeated failures or failed health checks.",
-            "timeout": "Upstream or dependency timed out handling the request.",
-            "auth_failure": "Authentication/authorization failed (expired token, missing permissions, or misconfiguration).",
-            "db_connection": "Database connection pool exhausted or connection refused.",
-            "dns_resolution": "DNS resolution failed for upstream host.",
-            "tls_handshake": "TLS handshake failed (bad cert, protocol mismatch).",
-            "null_pointer": "Application hit null/None reference and crashed.",
-            "resource_exhaustion": "System resources (CPU/file descriptors) exhausted.",
-            "network_partition": "Network partition or connectivity issue between components.",
+            "oom": "Сервис, вероятно, исчерпал память и был аварийно завершён.",
+            "crashloop": "Контейнер постоянно перезапускается из-за повторяющихся сбоев или неуспешных health-check.",
+            "timeout": "Верхний уровень или зависимость не ответили вовремя.",
+            "auth_failure": "Аутентификация/авторизация отклонена (истёкший токен, нехватка прав или неверная конфигурация).",
+            "db_connection": "Пул подключений к базе данных исчерпан либо соединение отвергнуто.",
+            "dns_resolution": "Не удалось разрешить DNS-имя целевого хоста.",
+            "tls_handshake": "TLS-рукопожатие завершилось ошибкой (сертификат, протокол или шифр).",
+            "null_pointer": "Приложение встретило null/None и аварийно завершилось.",
+            "resource_exhaustion": "Системные ресурсы (CPU/дескрипторы файлов) исчерпаны.",
+            "network_partition": "Сетевой разрыв или проблемы с связностью между компонентами.",
         }
-        cause = cause_map.get(label, f"Most likely incident category: {label}.")
+        cause = cause_map.get(label, f"Наиболее вероятная категория инцидента: {label}.")
         checks: List[str] = [
-            "Confirm timeframe of failure in logs and recent deploys.",
-            "Check service and pod/resource metrics (CPU, memory, restarts) around the incident window.",
-            "Inspect recent configuration or secrets changes.",
+            "Подтвердите временной интервал сбоя в логах и сопоставьте с последними релизами.",
+            "Проверьте метрики сервисов/подов (CPU, память, рестарты) вокруг окна инцидента.",
+            "Изучите недавние изменения конфигураций и секретов.",
         ]
         if label == "oom" or "oom" in result.signatures:
             checks += [
-                "Inspect container memory limits/requests and current usage.",
-                "Review heap/thread dumps if available.",
-                "Check for memory leaks or unbounded caches.",
-                "Ensure JVM/Runtime memory flags are configured correctly.",
+                "Проверьте лимиты/requests памяти контейнера и фактическое потребление.",
+                "Если доступны, изучите дампы heap/thread.",
+                "Исключите утечки памяти и неограниченные кэши.",
+                "Убедитесь, что флаги памяти JVM/рантайма настроены корректно.",
             ]
         if label in ("timeout",):
             checks += [
-                "Measure latency between service and dependencies.",
-                "Verify retry/backoff settings and circuit breakers.",
-                "Check for slow queries or downstream saturation.",
+                "Замерьте задержки между сервисом и зависимостями.",
+                "Проверьте настройки ретраев/бэк-оффов и circuit breaker.",
+                "Поиск потенциально медленных запросов либо перегруженных зависимостей.",
             ]
         if label in ("auth_failure",):
             checks += [
-                "Verify tokens/credentials validity and scopes.",
-                "Check clock skew between services.",
-                "Review authentication provider health and rate limits.",
+                "Проверьте валидность токенов/учётных данных и нужные scope.",
+                "Сверьте время между сервисами (clock skew).",
+                "Проверьте состояние провайдера аутентификации и его квоты.",
             ]
         if label in ("db_connection",):
             checks += [
-                "Check DB connection pool size vs load.",
-                "Inspect database for locks or slow queries.",
-                "Verify database host/port/DNS correctness.",
+                "Сопоставьте размер пула БД с текущей нагрузкой.",
+                "Проверьте базу на блокировки или медленные запросы.",
+                "Убедитесь в корректности host/port/DNS для подключения.",
             ]
         if label in ("dns_resolution",):
             checks += [
-                "Resolve target host from pod/host manually.",
-                "Check DNS server health and recent DNS changes.",
-                "Verify search domains and /etc/resolv.conf inside pod/container.",
+                "Попробуйте вручную резолвить хост из пода/хоста.",
+                "Проверьте здоровье DNS-серверов и свежие изменения записей.",
+                "Посмотрите search domains и /etc/resolv.conf внутри контейнера.",
             ]
         if label in ("tls_handshake",):
             checks += [
-                "Validate certificates (expiry, SANs, chain).",
-                "Check protocol/cipher compatibility between client and server.",
-                "Inspect ALPN/SNI configuration.",
+                "Проверьте сертификаты (срок, SAN, цепочка).",
+                "Сравните поддерживаемые протоколы/шифры клиента и сервера.",
+                "Проверьте настройки ALPN/SNI.",
             ]
         if label in ("crashloop",):
             checks += [
-                "Inspect startup probes/health checks and command overrides.",
-                "Review last logs before restart for root cause.",
-                "Confirm config/secret mounts exist and permissions are correct.",
+                "Проверьте startup/health‑пробы и переопределения команд.",
+                "Посмотрите последние логи перед рестартом для поиска первопричины.",
+                "Убедитесь, что конфиги/секреты смонтированы и права корректны.",
             ]
         if retrieved:
-            checks.append(f"Consult runbook: {retrieved[0]['title']} (score {retrieved[0]['score']:.2f}).")
+            checks.append(f"Изучите ранбук: {retrieved[0]['title']} (сходство {retrieved[0]['score']:.2f}).")
         # Ensure at least 5 checks
         while len(checks) < 5:
-            checks.append("Add extra diagnostic step: capture more logs and metrics.")
+            checks.append("Добавьте шаг диагностики: снимите дополнительные логи и метрики.")
         return cause, checks[:10]
 
     def verify_hypotheses(self, premise: str, hypotheses: List[str]) -> List[Dict]:
+        """
+        Прогоняет набор гипотез через NLI, чтобы отметить подтверждение/опровержение.
+        """
         results = []
         for hyp in hypotheses:
-            pred = self.models.nli({"text": premise, "text_pair": hyp})[0]
+            raw = self.models.nli({"text": premise, "text_pair": hyp})
+            pred = raw[0] if isinstance(raw, list) else raw
             results.append({"hypothesis": hyp, "label": pred["label"], "score": float(pred["score"])})
         return results
 
@@ -173,8 +201,11 @@ class IncidentPipeline:
         use_nli: bool = False,
         verbosity: int = 1,
     ) -> IncidentResult:
+        """
+        Полный пайплайн обработки логов: от предобработки до верификации.
+        """
         if not raw_text or not raw_text.strip():
-            raise ValueError("Logs input is empty. Please provide logs or stacktrace text.")
+            raise ValueError("Поле логов пустое. Пожалуйста, вставьте текст логов или стектрейса.")
         pre = preprocess_logs(raw_text)
         cls = self.classify(pre.cleaned_text, source)
         explanation = self.explain(pre.cleaned_text, verbosity=verbosity)
@@ -182,7 +213,7 @@ class IncidentPipeline:
         cause, checks = self.generate_cause_and_checks(pre, cls["label"], retrieved)
         verification = []
         if use_nli:
-            hypotheses = [cause] + [f"Runbook match: {r['title']}" for r in retrieved]
+            hypotheses = [cause] + [f"Совпадение с ранбуком: {r['title']}" for r in retrieved]
             verification = self.verify_hypotheses(pre.cleaned_text, hypotheses)
         return IncidentResult(
             incident_label=cls["label"],
@@ -198,4 +229,7 @@ class IncidentPipeline:
 
 
 def serialize_result(result: IncidentResult) -> str:
+    """
+    Упаковывает результат в JSON-строку.
+    """
     return json.dumps(asdict(result), indent=2, ensure_ascii=False)

preprocess.py

@@ -12,12 +12,18 @@ TIMESTAMP_RE = re.compile(r"\b\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?\b
 
 @dataclass
 class PreprocessResult:
+    """
+    Результат предобработки: очищенный текст, сигнатуры и замаскированные значения.
+    """
     cleaned_text: str
     signatures: List[str]
     masked: List[str]
 
 
 def detect_signatures(text: str) -> List[str]:
+    """
+    Ищет в тексте характерные маркеры (стектрейсы, уровни логов и т.д.).
+    """
     signatures = []
     if re.search(r"Traceback|Exception|Error:|Caused by:", text, re.IGNORECASE):
         signatures.append("stacktrace")
@@ -35,6 +41,9 @@ def detect_signatures(text: str) -> List[str]:
 
 
 def mask_sensitive(text: str) -> Tuple[str, List[str]]:
+    """
+    Маскирует UUID/IP/почты/пути, возвращая новый текст и список найденных значений.
+    """
     masked = []
 
     def _mask(pattern: re.Pattern, placeholder: str, value: str) -> str:
@@ -51,6 +60,9 @@ def mask_sensitive(text: str) -> Tuple[str, List[str]]:
 
 
 def truncate_logs(text: str, head_lines: int = 120, tail_lines: int = 80, max_lines: int = 400) -> str:
+    """
+    Обрезает длинные логи, сохраняя головы/хвост и вставляя разделитель.
+    """
     lines = text.splitlines()
     if len(lines) <= max_lines:
         return text
@@ -60,6 +72,9 @@ def truncate_logs(text: str, head_lines: int = 120, tail_lines: int = 80, max_li
 
 
 def preprocess_logs(raw_text: str) -> PreprocessResult:
+    """
+    Комплексная подготовка логов к классификации: нормализация, маскировка, сигнатуры.
+    """
     normalized = raw_text.strip()
     truncated = truncate_logs(normalized)
     masked_text, masked = mask_sensitive(truncated)

requirements.txt

@@ -1,4 +1,4 @@
-gradio==4.44.0
+gradio==4.44.1
 transformers==4.38.2
 torch>=2.2.0,<3.0
 sentence-transformers==2.5.1

retrieval.py

@@ -9,18 +9,27 @@ from sentence_transformers import CrossEncoder, SentenceTransformer, util
 
 @dataclass
 class RunbookDoc:
+    """
+    Представляет один Markdown-ранбук локальной БЗ.
+    """
     path: str
     title: str
     content: str
 
 
 class RunbookRetriever:
+    """
+    Отвечает за загрузку локальной базы знаний и поиск по ней.
+    """
     def __init__(
         self,
         kb_dir: str = "kb",
         embed_model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
         reranker_name: Optional[str] = "cross-encoder/ms-marco-MiniLM-L-6-v2",
     ):
+        """
+        Загружает все ранбуки и подготавливает модели (эмбеддер + опциональный reranker).
+        """
         self.kb_dir = kb_dir
         # Force CPU to avoid CUDA capability mismatches in WSL/GPUs.
         self.device = torch.device("cpu")
@@ -42,6 +51,9 @@ class RunbookRetriever:
             self.doc_embeddings = None
 
     def _load_docs(self) -> List[RunbookDoc]:
+        """
+        Читает Markdown-файлы из kb_dir и превращает их в список RunbookDoc.
+        """
         docs: List[RunbookDoc] = []
         if not os.path.isdir(self.kb_dir):
             return docs
@@ -56,6 +68,9 @@ class RunbookRetriever:
         return docs
 
     def search(self, query: str, top_k: int = 3):
+        """
+        Находит топ-k релевантных ранбуков по косинусному сходству (и reranker'у, если доступен).
+        """
         if not self.docs or self.doc_embeddings is None:
             return []
         query_emb = self.embed_model.encode(query, convert_to_tensor=True, device=self.device)