Konfiguration

Alle Konfigurationsoptionen fuer das KnowledgeSDK an einem Ort — Umgebungsvariablen, Collection-Registry, LLM-Provider, Feedback-Store und Schwellenwerte.

Umgebungsvariablen

Such-Server

Indexer

Classifier

CLI / Single-Binary

Die CLI akzeptiert dieselben Umgebungsvariablen wie der Docker-Server:

QMD_INDEX_PATH      Pfad zur SQLite-Datenbank
QMD_EMBED_PROVIDER  none | openai | voyage
QMD_SEARCH_MODE     fts | hybrid
QMD_API_KEY         API-Key fuer Auth (Serve-Modus)
GITHUB_TOKEN        Fuer GitHub-Plugin (Index-Modus)

Collection-Registry

Die Collection-Konfiguration definiert pro Collection Repositories, Keywords und Sub-Themen. Sie liegt entweder in lib/classifier-config.ts (bei Library-Nutzung) oder in der config.json (bei Docker/CLI).

Struktur

interface ClassifierCollectionMeta {
  name: string;          // z.B. "engine"
  repos: RepoRef[];      // Zugeordnete GitHub-Repositories
  keywords: WeightedKeyword[];  // Gewichtete Keywords
  subThemes: SubTheme[]; // Sub-Themen fuer feingranulare Zuordnung
}

Beispiel: Engine-Collection

{
  name: 'engine',
  repos: [
    { org: '5minds', name: 'ProcessCube.Engine.MonoRepo', branch: 'main' },
  ],
  keywords: [
    { term: 'bpmn', weight: 2.0 },
    { term: 'workflow', weight: 2.0 },
    { term: 'timer', weight: 1.0 },
    { term: 'user-task', weight: 1.0 },
    { term: 'gateway', weight: 1.0 },
    // ...
  ],
  subThemes: [
    { name: 'bpmn/timer-events', keywords: ['timer', 'cron', 'delay'], docPath: '/engine/bpmn/timer-events' },
    { name: 'bpmn/gateways', keywords: ['gateway', 'exclusive', 'parallel'], docPath: '/engine/bpmn/gateways' },
    // ...
  ],
}

Keyword-Gewichte

Mehrere Keyword-Treffer derselben Collection verstaerken den Score (Multi-Hit-Bonus).

Repositories

Jede Collection kann ein oder mehrere GitHub-Repositories zugeordnet bekommen. Wenn ein Ticket aus einem dieser Repos stammt, erhaelt die Collection einen starken Repo-Match-Bonus (Gewicht 3.0x).

Sub-Themen

Innerhalb einer Collection ermoeglichen Sub-Themen eine feingranulare Zuordnung:

subThemes: [
  {
    name: 'bpmn/timer-events',
    keywords: ['timer', 'cron', 'delay'],
    docPath: '/engine/bpmn/timer-events',
  },
]

Das Sub-Thema mit den meisten Keyword-Treffern wird als subTheme im Ergebnis geliefert.

LLM-Provider

Der Slow Path nutzt ein LLM fuer unsichere Klassifikationen (Konfidenz unter dem Fast Path Threshold). Das LLM ist optional — ohne Konfiguration wird immer der regelbasierte Fast Path genutzt.

Konfiguration

{
  llm: {
    provider: 'openai',        // oder 'anthropic'
    model: 'gpt-4o-mini',      // guenstig, schnell, ausreichend
    temperature: 0,            // deterministisch
    maxTokens: 300,            // JSON-Response braucht nicht viel
  },
  fastPathThreshold: 0.8,     // Ab diesem Score kein LLM noetig
}

Provider-Vergleich

Feedback-Store

Der Feedback-Store speichert Klassifikationen und Korrekturen in einer SQLite-Datenbank mit FTS5-Volltextsuche. Er ermoeglicht das Self-Improvement des Classifiers.

Datenbank-Pfad

Verhalten

• Die Feedback-DB wird automatisch erstellt, wenn sie nicht existiert
• Sie ist unabhaengig vom Such-Index (index.sqlite)
• Kann geloescht werden, ohne die Suche zu beeintraechtigen — nur gelerntes Feedback geht verloren
• Jede Klassifikation wird gespeichert (fuer spaeteres Feedback)
• Korrekturen werden per correlationId zugeordnet

Tabellen

Fast Path Threshold

Der Schwellenwert bestimmt, ab welchem Score der Classifier ohne LLM entscheidet:

{
  fastPathThreshold: 0.8, // Default
}

Zusaetzlich muss der Abstand zum zweitbesten Kandidaten mindestens 0.2 betragen, damit der Fast Path greift. Bei knappen Entscheidungen wird immer das LLM befragt.

Autorisierung

Lokal (Entwicklung)

Ohne CLASSIFIER_API_KEY und QMD_API_KEY sind alle Endpoints offen.

Produktion (K8s)

Die Keys werden ueber ExternalSecrets aus 1Password geladen:

1Password (docs-prd)
    → ExternalSecret (docs-env-secret)
        → Env-Vars CLASSIFIER_API_KEY, QMD_API_KEY im Pod

Die jeweiligen Keys muessen als Felder im 1Password-Item docs-prd hinterlegt sein.