Чат-бот по документации Halcyon

Ответы на вопросы на основе локального корпуса документов, построенные на Indexing, Search и Chat API от Glean и представленные как единый MCP-инструмент.

Веб-интерфейса нет. Интерфейс чата — это MCP-клиент: Cursor, Claude Desktop или любой другой.

Как это работает

data/Halcyon Shared Drive/  ->  Indexing API  ->  Search API  ->  Chat API  ->  {answer, sources, diagnostics}

Search выполняется до Chat, и Chat никогда не извлекает данные: отрывки извлекаются явно и передаются в него. Если ничего не проходит порог релевантности (пересечение терминов с вопросом), ответ — честное «проиндексированный контент не найден», и Chat не вызывается.

Related MCP server: faq-rag

Настройка

Требуются Poetry и Python 3.12+.

poetry config virtualenvs.in-project true   # keeps the venv at ./.venv
poetry install
cp .env.example .env      # then fill in the tokens

.env находится в .gitignore. Никогда не коммитьте реальные токены.

Необязательные, со значениями по умолчанию: GLEAN_DOC_ID_PREFIX (halcyon), GLEAN_TOP_K (5), GLEAN_MAX_SNIPPET_SIZE (2000), GLEAN_MIN_TERM_OVERLAP (0.30), GLEAN_CHAT_TIMEOUT_MS (60000).

Два токена структурно разделены: Settings.for_indexing() читает GLEAN_INDEXING_TOKEN, Settings.for_query() читает GLEAN_CLIENT_TOKEN и никогда не касается переменной индексации.

Использование

poetry run python -m glean_chat_bot     # the MCP server, on stdio
poetry run glean-index --dry-run        # extract and report, send nothing
poetry run glean-index                  # extract and bulk-push
poetry run glean-index --process-now    # ask Glean to process immediately (1 per 3h)
poetry run pytest                       # contract tests: no network, no tokens
poetry run pytest -m live               # the eval set, against real Glean

Добавьте -v для отладочного журналирования.

Индексация асинхронна: glean-index возвращает управление, как только Glean принял документы, за несколько минут до того, как они станут доступны для поиска. Подтвердите полное покрытие в консоли администратора Glean, прежде чем полагаться на ответы.

Конфигурация MCP-клиента

{
  "mcpServers": {
    "glean-company-docs": {
      "command": "/absolute/path/to/glean-chat-bot/.venv/bin/python",
      "args": ["-m", "glean_chat_bot"],
      "env": {
        "GLEAN_INSTANCE": "support-lab",
        "GLEAN_CLIENT_TOKEN": "...",
        "GLEAN_ACT_AS": "you@example.com",
        "GLEAN_DATASOURCE": "interviewds3"
      }
    }
  }
}

Один инструмент, ask_company_docs(question, top_k=None, include_citations=True) -> dict, возвращающий {answer, sources, diagnostics}. diagnostics сообщает, что было искано и что вернулось, чтобы вызывающая модель могла отличить «ничего не совпало» от «моя формулировка не подошла» и повторить попытку соответственно.

Структура

glean_chat_bot/
  __main__.py      `python -m glean_chat_bot`, the MCP server: one tool over query.ask.ask()
  client.py        indexing and query client factories, the ActAs header
  extraction.py    one adapter per file type, path signals, walk
  indexing.py      the whole write path, behind the `glean-index` command
  models.py        Passage, Source, Answer, ExtractedDoc (pydantic)
  query/           search.py (search -> Passage, the relevance floor)
                   chat.py (chat -> answer + resolved citations)
                   ask.py (ask() — the single orchestration function)
  utils/           config.py (env loading, one Settings, two constructors)
                   logging.py (log format, timing wrapper on every Glean call)
data/              the corpus
docs/              extraction notes
tests/             test_contract.py (the invariants, offline)
                   eval_cases.py + test_eval_live.py (the eval set, `-m live`)

Poetry для зависимостей и упаковки, Ruff для линтера и форматирования. Запустите poetry run ruff check . и poetry run ruff format . перед коммитом.

Ещё не реализовано

Права групп и пользователей, фильтрация по отделам, аннотации свежести, манифест хешей контента, переписывание запросов и адаптивные повторные попытки, потоковая передача, память разговора, повторные попытки и экспоненциальная задержка, Docker, CI.