Knowledge Base Hook

useKnowledgeBase

The knowledge-base session-orchestration hook over the core KnowledgeBaseEngine contract. It owns the full session so no consuming block re-implements it: the raw-document store (documents + add / remove / clear), the embedding-model load lifecycle (via useModelLoad, key kb-embedding:${id} preserved verbatim), chunking + embedding-model config, busy / error / stats, and — the load-bearing part — re-ingest of the whole raw-document store on either an engine-kind toggle or an embedding-model switch.

The active engine is produced by an injected createEngine(kind) factory, so the hook consumes only the KnowledgeBaseEngine contract and never imports a specific engine. A core-only factory keeps @localmode/langchain entirely out of the session; a toggle-capable factory dynamically imports the LangChain engine (await import('@localmode/langchain')) only when the toggle flips.

import { useKnowledgeBase } from '@localmode/react';
import { createKnowledgeBaseEngine } from '@localmode/core';
import { transformers, isModelCached } from '@localmode/transformers';

const kb = useKnowledgeBase({
  embeddingModelId: 'Xenova/bge-small-en-v1.5',
  createEmbeddingModel: (id, onProgress) => transformers.embedding(id, { onProgress }),
  isModelCached: (id) => isModelCached(id),
  // core-only factory: never imports @localmode/langchain
  createEngine: () =>
    createKnowledgeBaseEngine({
      embeddingModel: transformers.embedding('Xenova/bge-small-en-v1.5'),
      getLanguageModel: async () => transformers.languageModel('onnx-community/granite-4.0'),
    }),
});

Options

Return Value

Session

Embedding-model load lifecycle

The engine contract

The hook is engine-agnostic: it talks only to the KnowledgeBaseEngine contract in @localmode/core. Both engines implement it:

An engine-kind toggle or an embedding-model switch drives a single effect (keyed on [engineKind, embeddingModelId]) that recreates the engine and, if the raw-document store is non-empty, re-ingests the whole corpus through it with visible progress. Regular addDocuments calls ingest incrementally.

Blocks