Skip to Content
KnowledgeSDKArchitektur

Architektur

Das KnowledgeSDK ist modular aufgebaut. Jede Komponente hat eine klar definierte Aufgabe und kann unabhaengig verwendet werden.

Modul-Uebersicht

Das SDK gliedert sich in zwei NPM-Pakete mit folgenden Modulen:

@processcube-io/knowledge-sdk

ModulBeschreibung
CoreSearchStore, Types, Embedding-Adapter, Backpressure-Limiter, Result-Formatter
IndexerPlugin-Registry, generischer Indexer mit Delta-Erkennung (SHA-256 Content-Hash)
PluginsBuilt-in Content-Sources: Dateisystem und GitHub
AdapterFramework-Integrationen: Next.js, Express, Hono, Standalone HTTP-Server
MCPModel Context Protocol Server fuer AI-Assistenten
ClassifierTicket-Classifier mit Scoring, LLM-Integration und Feedback-Store
AuthAuthentifizierungs-Plugins: API-Key (Env) und Odoo (REST + Cache)
CLIEntrypoints fuer Docker-Images und Single-Binary

@processcube-io/knowledge-sdk-ui

ModulBeschreibung
SearchDialogKonfigurierbare React-Komponente mit Cmd+K, Collection-Filter, Keyboard-Navigation

Datenfluss

Das folgende Diagramm zeigt den Weg von den Inhaltsquellen bis zur Suchantwort:

SearchStore

Der SearchStore ist das zentrale Interface fuer alle Suchoperationen. Er wird einmalig erstellt und von den Adaptern wiederverwendet.

const store = await createSearchStore({
  dbPath: './data/index.sqlite',
  searchMode: 'hybrid',          // 'fts' oder 'hybrid'
  embedProvider: {
    provider: 'voyage',
    apiKey: process.env.VOYAGE_API_KEY,
  },
});

Der Store bietet folgende Methoden:

MethodeBeschreibung
search(query, options?)Suche ausfuehren und SearchResponse zurueckgeben
listCollections()Alle Collections mit Dokumentanzahl auflisten
isHybridSearch()Pruefen ob Hybrid-Modus aktiv ist
close()Store und Datenbank-Verbindung schliessen

Der Store verwaltet intern die SQLite-Verbindung, den BM25-Index (FTS5) und — bei Hybrid-Suche — den Vektor-Index. Alle Operationen sind synchron auf SQLite-Ebene, was Thread-Safety garantiert.

Embedding-Adapter

Fuer die Hybrid-Suche werden Texte in Vektoren umgewandelt. Das SDK unterstuetzt drei Provider:

ProviderModellDimensionenBeschreibung
voyagevoyage-31024Voyage AI — optimiert fuer Retrieval, empfohlen
openaitext-embedding-3-small1536OpenAI Embeddings
none——Nur BM25, keine Vektoren (Standard)

Die Wahl des Embedding-Providers beeinflusst sowohl den Indexer (Vektoren erzeugen) als auch den SearchStore (Query-Vektoren berechnen). Beide muessen den gleichen Provider verwenden.

Konfiguration

const embedProvider = {
  provider: 'voyage',           // 'none' | 'openai' | 'voyage'
  apiKey: process.env.VOYAGE_API_KEY,
  model: 'voyage-3',           // Optional, Provider-Default wird verwendet
  dimensions: 1024,            // Optional, Provider-Default wird verwendet
  domainContext: 'eine technische Dokumentation ueber Workflow-Engines',
  maxRetries: 3,               // Retries bei API-Fehlern
  retryBaseMs: 1000,           // Basis-Wartezeit fuer exponentielles Backoff
};

Der domainContext wird fuer Query Expansion genutzt — der Embedding-Provider generiert damit zusaetzliche Suchvarianten, die die Ergebnisqualitaet verbessern.

Zusammenspiel der Komponenten

Der typische Ablauf in einer Anwendung:

  1. Indexer liest Inhalte ueber Plugins (Dateisystem, GitHub) und erstellt die SQLite-Datenbank mit BM25-Index und optional Vektor-Embeddings. Die Delta-Erkennung sorgt dafuer, dass nur geaenderte Dokumente neu indexiert werden.

  2. SearchStore oeffnet die Datenbank und stellt die Such-API bereit. Bei einer Anfrage wird je nach Modus (fts oder hybrid) die passende Such-Pipeline ausgefuehrt.

  3. Adapter binden den Store in ein HTTP-Framework ein und uebersetzen Query-Parameter in Store-Aufrufe. Optional kann ein Auth-Plugin vorgeschaltet werden.

  4. MCP-Server nutzt den gleichen Store und stellt die Suche als Tool fuer AI-Assistenten bereit (search_docs, list_collections).

  5. UI-Komponente (separates Paket) kommuniziert ueber die HTTP-API mit dem Adapter und stellt eine fertige Suchoberflaeche bereit.

Naechste Schritte

Getting StartedIndexer & Collections