fix(indexer): close PageIndex's local SQLite connection and forward LLM credentials

[sebastianbraun25]

Note

This PR was created in collaboration between a human and AI: implementation, tests, and
PR text were created by an AI assistant under the guidance and review of the human author.

Problem

index_long_document() in openkb/indexer.py (local PageIndex indexing for
long PDFs) has two related robustness problems observed during a real batch
openkb add run:

1. The local PageIndex SQLite connection it opens (.openkb/pageindex.db) is
   never closed. If a later step in the same add fails, the mutation
   rollback in openkb/mutation.py tries to unlink()/rename
   pageindex.db/-wal/-shm — on Windows this hits WinError 32 because
   the connection opened earlier in the same process is still holding the
   file open, leaving a dirty mutation journal and aborting the rest of the
   batch (fix(indexer): close PageIndex's local SQLite connection so rollback doesn't hit WinError 32 #249).
2. PageIndex's own internal LLM calls (TOC/tree/summary generation) don't
   receive the KB's resolved model credentials. index_long_document() only
   reads PAGEINDEX_API_KEY (PageIndex Cloud auth) — a custom
   LLM_API_KEY/gateway base_url (the same credentials compiler.py's own
   _llm_call/_llm_call_async use) never reaches PageIndex, which falls
   back to LiteLLM's default provider-key/env-var lookup instead ([Bug] PageIndex long document indexing fails with custom OPENAI_API_BASE / 401 Unauthorized #219).

Root Cause

1. col = client.collection() opens a WAL-mode SQLite connection via
   PageIndex's local backend, and nothing in index_long_document() ever
   closes it — the connection lives for the rest of the process.
2. index_long_document() never calls openkb.config .resolve_credential_bundle(), so it has no api_key/base_url to give
   PageIndex in the first place. Separately, the pinned pageindex version
   only accepts LLM credentials for its own calls via a dedicated
   IndexConfig(llm_params={...}) field (scoped per-call through
   pageindex.config.llm_params_scope, context-isolated so it's safe under
   concurrent multi-KB use) — not via PageIndexClient(api_key=...), which is
   PageIndex Cloud's own auth and unrelated to the underlying model's LLM
   credentials in local mode.

Solution / Changes

• openkb/indexer.py:
  • New _close_pageindex_client() helper: best-effort closes
    client._backend._storage (the only place the pinned pageindex exposes
    a close() — there's no public API on PageIndexClient/Collection
    itself). A no-op in cloud mode (no local backend/storage). Never raises.
  • index_long_document()'s whole body now runs inside a try/finally
    that calls the helper above — closed on both the success and the failure
    path.
  • index_long_document() now resolves resolve_credential_bundle(kb_dir)
    and forwards it into _build_index_config().
  • _build_index_config() takes an optional bundle and forwards its
    non-empty api_key/base_url as IndexConfig(llm_params={...}), guarded
    by the same IndexConfig.model_fields check already used for
    max_concurrency — degrades gracefully (with a warning) against an older
    pinned PageIndex that predates the llm_params field.
• tests/test_indexer.py:
  • TestBuildIndexConfigLlmParams: bundle → llm_params forwarding
    (full/partial/empty/None bundle, and the unsupported-version fallback).
  • TestClosePageindexClient: closes the local backend's storage, is a
    no-op for a client without one, and swallows a close() exception.
  • TestIndexLongDocument: closes the client on both success and failure,
    and the resolved credential bundle reaches the real IndexConfig
    passed to PageIndexClient (not just the isolated _build_index_config
    unit tests).

Backward compatible: no config/CLI surface changes. A KB with no custom
LLM_API_KEY/base_url sees no llm_params at all (unchanged behavior).

Issues

Resolves #249.
Resolves #219.

[muhammadyaseen]

I ran into the credential-forwarding problem addressed by this PR while using OpenKB with a LiteLLM Gateway (using Azure-hosted models) protected by Cloudflare Access.

The gateway requires these additional headers on every LLM request:

extra_headers:
  CF-Access-Client-Id: "<secret>"
  CF-Access-Client-Secret: "<secret>"

OpenKB already forwarded extra_headers for the normal compiler path, so short documents could already use the gateway. However, long PDFs routed through PageIndex did not receive the configured headers and the internal LiteLLM calls therefore could not authenticate with the gateway.

As a local workaround, I patched openkb/indexer.py to forward the resolved headers into PageIndex:

from pageindex import IndexConfig, PageIndexClient, set_llm_params
from openkb.config import (
    load_config,
    resolve_concurrency,
    resolve_extra_headers,
)

# Inside index_long_document():
config = load_config(openkb_dir / "config.yaml")
set_llm_params(extra_headers=resolve_extra_headers(config))

The configured Cloudflare headers then appeared in PageIndex’s LiteLLM parameters, resolving the issue. I therefore wanted to support the implementation in this PR of passing api_key, base_url, extra_headers to PageIndex as well.

I tested against OpenKB 0.4.5 with long PDFs exceeding pageindex_threshold. No credential values are included here.