@equationalapplications/core-llm-wiki 7.4.0 → 7.5.0

package/README.md

@@ -799,6 +799,47 @@ const result = await wiki.runOntologyBackfill(entityId);
   `config.prompts.ontologyBackfillSystemPrompt` (template may use `{{facts}}`
   and the ontology placeholders).
 
+#### Classifier mode (optional)
+
+A System-One classifier (for example TypeSafe's Jev, an OpenJev-style open model, or a local ONNX classifier) can type facts during backfill without generating text. Add `classify` to your provider and opt in:
+
+```ts
+const wiki = createWiki(db, {
+  llmProvider: { generateText, classify },
+  config: { ontology: { backfillClassifier: 'auto', classifyMinConfidence: 0.5 } },
+});
+await wiki.runOntologyBackfill('user-1');                        // uses classify
+await wiki.runOntologyBackfill('user-1', { classifier: 'llm' }); // force the generative path
+```
+
+- Providing `classify` changes nothing by itself. The default is `'llm'`.
+- Each untyped fact gets one `choice` question over the entity manifest's node types. Answers below `classifyMinConfidence` (default 0.5) are left untyped and retried after the cooldown.
+- **No edges are proposed in classifier mode** (`edgesAdded: 0`): a classifier cannot extract edge targets. Run with `classifier: 'llm'` when you want edges.
+- Manifests with more than 255 node types, or providers without `classify`, use the generative path.
+- Answers are validated as untrusted. Off-list choices and out-of-range probabilities count toward `failedValidation`. A thrown `classify` counts toward `skipped` and is retried on the next pass.
+
+Example adapter for Cloudflare Workers AI's `typesafe/jev`. This is illustrative, not a supported package; check the provider's current API reference before use.
+
+```ts
+const classify: LLMProvider['classify'] = async ({ state, questions }) => {
+  const jevQuestions = Object.fromEntries(Object.entries(questions).map(([key, q]) => [key,
+    q.kind === 'choice' ? { type: 'choice', instructions: q.instructions, criteria: Object.fromEntries(q.options.map((o) => [o, o])) }
+    : q.kind === 'score' ? { type: 'score', instructions: q.instructions, criteria: q.levels }
+    : { type: 'noul', instructions: q.instructions },
+  ]));
+  const res = await env.AI.run('typesafe/jev', { state, questions: jevQuestions });
+  const answers = Object.fromEntries(Object.entries(res.answers).map(([key, a]: [string, any]) => [key,
+    a.type === 'choice' ? { kind: 'choice', choice: a.choice, confidence: a.confidence, probabilities: a.probabilities }
+    : a.type === 'score' ? {
+        kind: 'score', score: a.score, confidence: a.confidence,
+        probabilities: Object.keys(a.probabilities).sort((x, y) => Number(x) - Number(y)).map((k) => a.probabilities[k]),
+      }
+    : { kind: 'binary', probability: a.noul },
+  ]));
+  return { answers };
+};
+```
+
 ## OKF Import/Export
 
 The core package integrates with `@equationalapplications/core-okf` to seamlessly adapt wiki data dumps to and from Open Knowledge Format (OKF) bundles (v0.1 and v0.2; `formatOkfBundle` defaults to the v0.2 / `llm-wiki/2` profile).

package/dist/{chunk-G5OR2VWD.mjs → chunk-3P7FAKJA.mjs}

@@ -2471,6 +2471,51 @@ var IngestionService = class {
   }
 };
 
+// src/utils/classifier.ts
+var isUnit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+function validateClassifierAnswer(response, key, question) {
+  try {
+    if (response === null || typeof response !== "object") return { ok: false, reason: "malformed" };
+    const answers = response.answers;
+    if (answers === null || typeof answers !== "object") return { ok: false, reason: "missing_answer" };
+    if (!Object.prototype.hasOwnProperty.call(answers, key)) return { ok: false, reason: "missing_answer" };
+    const raw = answers[key];
+    if (raw === null || typeof raw !== "object") return { ok: false, reason: "missing_answer" };
+    const a = raw;
+    if (a.kind !== question.kind) return { ok: false, reason: "kind_mismatch" };
+    if (question.kind === "choice") {
+      if (typeof a.choice !== "string" || !question.options.includes(a.choice)) return { ok: false, reason: "choice_not_offered" };
+      if (!isUnit(a.confidence)) return { ok: false, reason: "invalid_probability" };
+      const probs = a.probabilities;
+      if (probs === null || typeof probs !== "object" || Array.isArray(probs)) return { ok: false, reason: "invalid_probability" };
+      const probabilities = {};
+      for (const [k, v] of Object.entries(probs)) {
+        if (!isUnit(v)) return { ok: false, reason: "invalid_probability" };
+        probabilities[k] = v;
+      }
+      return { ok: true, answer: { kind: "choice", choice: a.choice, confidence: a.confidence, probabilities } };
+    }
+    if (question.kind === "binary") {
+      if (!isUnit(a.probability)) return { ok: false, reason: "invalid_probability" };
+      return { ok: true, answer: { kind: "binary", probability: a.probability } };
+    }
+    const maxScore = question.levels.length - 1;
+    if (typeof a.score !== "number" || !Number.isFinite(a.score) || a.score < 0 || a.score > maxScore) {
+      return { ok: false, reason: "score_out_of_range" };
+    }
+    if (!isUnit(a.confidence)) return { ok: false, reason: "invalid_probability" };
+    if (!Array.isArray(a.probabilities) || !a.probabilities.every(isUnit)) return { ok: false, reason: "invalid_probability" };
+    return { ok: true, answer: { kind: "score", score: a.score, confidence: a.confidence, probabilities: a.probabilities.slice() } };
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+}
+function classifierStateForFact(fact) {
+  const parts = [fact.title, fact.body];
+  if (Array.isArray(fact.tags) && fact.tags.length > 0) parts.push(`Tags: ${fact.tags.join(", ")}`);
+  return parts.join("\n\n");
+}
+
 // src/repositories/BaseRepository.ts
 var BaseRepository = class {
   constructor(db, prefix) {
@@ -3539,7 +3584,7 @@ var MaintenanceService = class {
     if (!ontologyService) {
       return { ...zeroed, remaining: 0, deferred: 0 };
     }
-    const { mode } = await ontologyService.getEffectiveState(entityId);
+    const { mode, manifest: effectiveManifest } = await ontologyService.getEffectiveState(entityId);
     if (mode === "off") {
       const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
       return { ...zeroed, remaining: 0, deferred: counts2.deferred };
@@ -3549,6 +3594,14 @@ var MaintenanceService = class {
       const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
       return { ...zeroed, remaining: counts2.eligible, deferred: counts2.deferred };
     }
+    const classifierMode = options?.classifier ?? this.options.config?.ontology?.backfillClassifier ?? "llm";
+    const classify = this.options.llmProvider.classify;
+    if (classifierMode === "auto" && typeof classify === "function") {
+      const slugs = effectiveManifest.node_types.map((n) => n.type);
+      if (slugs.length > 0 && slugs.length <= 255) {
+        return this._runClassifierBackfill(entityId, candidates, effectiveManifest, now, recheckCutoff);
+      }
+    }
     const ontologyContext = await ontologyService.buildPromptContext(entityId);
     const toPromptShape = (f) => ({ id: f.id, title: f.title, body: f.body, tags: f.tags });
     const buildPrompt = (facts) => this.promptService.buildOntologyBackfillPrompt(
@@ -3627,6 +3680,87 @@ var MaintenanceService = class {
       deferred: counts.deferred
     };
   }
+  /**
+   * Classifier-mode backfill (spec §7.3): one `choice` question per untyped
+   * fact over the effective manifest's node-type slugs. Accepted answers go
+   * through `_applyOntologyBackfillBatch` exactly like LLM classifications.
+   * No edges are proposed.
+   */
+  async _runClassifierBackfill(entityId, candidates, manifest, now, recheckCutoff) {
+    const provider = this.options.llmProvider;
+    const rawMin = this.options.config?.ontology?.classifyMinConfidence;
+    const minConfidence = typeof rawMin === "number" && Number.isFinite(rawMin) && rawMin >= 0 && rawMin <= 1 ? rawMin : 0.5;
+    const rawConcurrency = this.options.config?.chunkConcurrency ?? 1;
+    const concurrency = Number.isFinite(rawConcurrency) && rawConcurrency >= 1 ? Math.floor(rawConcurrency) : 1;
+    const question = {
+      kind: "choice",
+      options: manifest.node_types.map((n) => n.type),
+      instructions: "Choose the ontology node type that best describes this fact.\n" + manifest.node_types.map((n) => `- ${n.type}: ${n.description}`).join("\n")
+    };
+    const outcomes = await withConcurrency(
+      candidates.map((fact) => async () => {
+        let response;
+        try {
+          response = await provider.classify({ state: classifierStateForFact(fact), questions: { okf_type: question } });
+        } catch {
+          return { fact, kind: "threw" };
+        }
+        const checked = validateClassifierAnswer(response, "okf_type", question);
+        if (!checked.ok) return { fact, kind: "invalid", reason: checked.reason };
+        if (checked.answer.kind !== "choice") return { fact, kind: "invalid", reason: "kind_mismatch" };
+        if (checked.answer.confidence < minConfidence) return { fact, kind: "low_confidence" };
+        return { fact, kind: "accepted", okfType: checked.answer.choice };
+      }),
+      concurrency
+    );
+    const attempted = outcomes.filter((o) => o.kind !== "threw").map((o) => o.fact);
+    const skipped = outcomes.length - attempted.length;
+    const classifications = outcomes.filter((o) => o.kind === "accepted").map((o) => ({ id: o.fact.id, okf_type: o.okfType }));
+    const invalidCount = outcomes.filter((o) => o.kind === "invalid").length;
+    let typed = 0;
+    let failedValidation = 0;
+    let edgesAdded = 0;
+    let aborted = false;
+    if (attempted.length > 0) {
+      const applied = await this._applyOntologyBackfillBatch(
+        entityId,
+        { batch: attempted, classifications, ontologyUpdates: void 0 },
+        now
+      );
+      aborted = applied.abortedOntologyOff;
+      if (!aborted) {
+        typed = applied.typed;
+        failedValidation = invalidCount + applied.failedValidation;
+        edgesAdded = applied.edgesAdded;
+      }
+    }
+    const diagBuffer = new DiagnosticBuffer();
+    const diagBase = { entityId, operation: "ontologyBackfill", trigger: "call" };
+    for (const o of outcomes) {
+      if (o.kind === "low_confidence") {
+        diagBuffer.push({ ...diagBase, code: "classification_low_confidence", detail: { factId: o.fact.id, reason: "below_threshold" } });
+      } else if (o.kind === "invalid") {
+        diagBuffer.push({ ...diagBase, code: "classification_invalid", detail: { factId: o.fact.id, reason: o.reason } });
+      } else if (o.kind === "threw") {
+        diagBuffer.push({ ...diagBase, code: "classification_invalid", detail: { factId: o.fact.id, reason: "classify_threw" } });
+      }
+    }
+    diagBuffer.flush(this.options);
+    const counts = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+    if (aborted) {
+      return { scanned: 0, typed: 0, failedValidation: 0, edgesAdded: 0, skipped, remaining: 0, deferred: counts.deferred };
+    }
+    this.searchService.evictCache(entityId);
+    return {
+      scanned: candidates.length,
+      typed,
+      failedValidation,
+      edgesAdded,
+      skipped,
+      remaining: counts.eligible,
+      deferred: counts.deferred
+    };
+  }
   /**
    * Applies one parsed backfill batch in its own transaction. Per-batch rather
    * than one transaction for the pass, so mergeEmergentUpdates semantics and
@@ -4330,8 +4464,7 @@ var EmbeddingService = class {
     }
   }
   async tryEmbedFact(fact, ctx) {
-    const embedFn = this.options.llmProvider.embed;
-    if (typeof embedFn !== "function") return { ok: false, kind: "no_provider" };
+    if (typeof this.options.llmProvider.embed !== "function") return { ok: false, kind: "no_provider" };
     let tagsStr;
     if (Array.isArray(fact.tags)) {
       tagsStr = fact.tags.join(" ");
@@ -4348,7 +4481,7 @@ var EmbeddingService = class {
     const text = clip(`${fact.title} ${fact.body} ${tagsStr}`.trim(), maxEmbedChars);
     let float32Vector;
     try {
-      const vector = await embedFn(text);
+      const vector = await this.options.llmProvider.embed(text);
       if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
         console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
         this.reportEmbed(ctx, fact, "embedding_failed", "invalid_vector");
@@ -4607,7 +4740,6 @@ var RetrievalService = class {
     const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
     const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
     const skipEmbed = weight === 0;
-    const embedFn = this.options.llmProvider.embed;
     let facts = [];
     let scoreByFactId;
     if (maxResults === 0) ; else if (trimmedQuery) {
@@ -4618,11 +4750,11 @@ var RetrievalService = class {
       const padLimit = (n) => n >= Number.MAX_SAFE_INTEGER ? n : n + draftPad;
       if (scoredEntityIds.length === 0) {
         usedEmbed = true;
-      } else if (!skipEmbed && embedFn) {
+      } else if (!skipEmbed && typeof this.options.llmProvider.embed === "function") {
         let rankerShouldRethrow = false;
         let pendingRankerFallbackError;
         try {
-          const queryVec = await embedFn(trimmedQuery);
+          const queryVec = await this.options.llmProvider.embed(trimmedQuery);
           if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
             throw new Error(
               "embed() returned an empty or non-finite vector. Falling back to keyword search."
@@ -5292,5 +5424,5 @@ var WriteService = class {
 };
 
 export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, DiagnosticBuffer, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-G5OR2VWD.mjs.map
-//# sourceMappingURL=chunk-G5OR2VWD.mjs.map
+//# sourceMappingURL=chunk-3P7FAKJA.mjs.map
+//# sourceMappingURL=chunk-3P7FAKJA.mjs.map