Imports:
  - Types:
      - Index
    Usages:
      - searching
    From: sententia/index
  - Types:
      - Provider
    From: sententia/llm/provider
  - Usages:
      - llm_generating
    From: sententia/llm

Usages:
  conventions: .goga/usages/conventions.md
  rag_prompt: |
    Правила формирования промпта для LLM:

    1. Открытие: "Используй следующий контекст, чтобы ответить на вопрос:"
    2. Блок контекста: тексты top релевантных чанков, объединённые двойным переводом строки,
       обёрнутые в triple-backticks
    3. Блок вопроса: текст query, обёрнутый в triple-backticks
    4. Инструкция: если контекст недостаточен — ответить
       "Недостаточно данных для ответа на данный вопрос"

Annotations: |
  Использовать `conventions` для правил написания кода и тестов.

  Клетка объединяет поиск релевантных чанков и генерацию ответа через LLM (RAG pipeline).
  Использовать практику `searching` для поиска релевантных чанков.
  Использовать практику `llm_generating` для генерации ответа.
  Использовать практику `rag_prompt` для формирования промпта.

---

"ask(query: str, index: Index, llm_provider: Provider, top: int = 10) -> answer:dict":
  location: rag.py
  annotations: |
    Полный RAG pipeline: поиск чанков → формирование промпта → вызов LLM.

    `query`: текст вопроса пользователя.
    `index`: экземпляр Index для поиска релевантных чанков.
    `llm_provider`: сконфигурированный LLM-провайдер (`Provider`).
    `top`: количество чанков для контекста. По умолчанию 10.
    `answer`: {"answer": str, "sources": list[str]} — сгенерированный ответ
              и список уникальных файлов-источников.

    Алгоритм:
      1. Найти релевантные чанки по практике `searching`
      2. Объединить тексты чанков через двойной перевод строки
      3. Сформировать промпт по практике `rag_prompt`
      4. Сгенерировать ответ по практике `llm_generating`
      5. Извлечь уникальные пути файлов-источников из найденных чанков (сохраняя порядок)

---

Author: Goga
CreatedAt: 16/05/26
Description: |
  RAG pipeline — поиск релевантных чанков и генерация ответа через LLM.
