Halcyon Docs Chatbot

Respuesta a preguntas fundamentada sobre un corpus de documentos local, construida sobre las API de Indexing, Search y Chat de Glean y expuesta como una única herramienta MCP.

No hay interfaz web. La interfaz de chat es un cliente MCP: Cursor, Claude Desktop o cualquier otro.

Cómo funciona

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

La búsqueda se ejecuta antes que el Chat, y el Chat nunca recupera: los pasajes se recuperan explícitamente y se pasan. Si nada supera el umbral de relevancia (solapamiento de términos con la pregunta), la respuesta es un honesto «no se encontró contenido indexado» y nunca se llama al Chat.

Related MCP server: faq-rag

Configuración

Requiere Poetry y 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 está en gitignore. Nunca confirmes tokens reales.

Opcionales, con valores predeterminados: 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).

Los dos tokens están separados estructuralmente: Settings.for_indexing() lee GLEAN_INDEXING_TOKEN, Settings.for_query() lee GLEAN_CLIENT_TOKEN y nunca toca la variable de indexación.

Uso

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

Añade -v para el registro de depuración.

La indexación es asíncrona: glean-index devuelve una vez que Glean ha aceptado los documentos, minutos antes de que sean buscables. Confirma la cobertura completa en la consola de administración de Glean antes de confiar en las respuestas.

Configuración del cliente 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"
      }
    }
  }
}

Una herramienta, ask_company_docs(question, top_k=None, include_citations=True) -> dict, que devuelve {answer, sources, diagnostics}. diagnostics informa de qué se buscó y qué se devolvió, para que el modelo que llama pueda distinguir «no coincidió nada» de «mi redacción falló» y reintentar en consecuencia.

Estructura

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 para dependencias y empaquetado, Ruff para lint y formato. Ejecuta poetry run ruff check . y poetry run ruff format . antes de confirmar.

Aún no implementado

Permisos de grupos y usuarios, filtrado por departamento, anotaciones de frescura, un manifiesto de hash de contenido, reescritura de consultas y reintento adaptativo, streaming, memoria de conversación, reintento y retroceso, Docker, CI.