@equationalapplications/core-llm-wiki 7.4.0 → 7.6.0

package/README.md

@@ -310,6 +310,36 @@ await wiki.promoteDraft(facts[0].id, 'user-1', { by: 'human:alice' }); // → st
 
 `promoteDraft` throws `WikiDraftNotFound` when no live draft with that id exists for the entity. The error is contextless by design. Promotion does not change `updated_at`, so a promoted fact keeps its recency position.
 
+## Grounding
+
+Opt-in, deterministic evidence check for LLM-authored facts. When on, writers you choose must quote the source they were shown. A fact whose quotes are missing or not found is stored as a `draft` (see [Draft Review](#draft-review)), not rejected. A fact whose quotes all check out is stored `stable` with a `process:grounding-check` verifier, so its `trustTier` is `machine-confirmed`. Default off: 7.x write behavior is unchanged.
+
+```ts
+new WikiMemory(db, {
+  llmProvider,
+  config: {
+    grounding: {
+      mode: 'draft',            // 'off' (default) | 'draft'
+      writers: ['ingest'],      // default ['ingest']; also 'librarian', 'heal'
+      minEvidenceChars: 20,     // shorter quotes count as absent
+      maxEvidence: 3,           // quotes asked for per fact
+      maxEvidenceChars: 300,
+    },
+  },
+});
+```
+
+- **What counts as source.**
+  - Ingest: the chunk text.
+  - Librarian: the `summary` of each event in the prompt.
+  - Heal: the `summary` of each recent event in the prompt, plus the bodies of non-draft document anchors. When heal is a writer, anchors are shown with their body clipped to 800 characters.
+  - Instructions, the ontology manifest, existing facts and identifiers never count, so a model cannot ground a claim by quoting them.
+- **The check.** Both sides are normalized with NFKC, whitespace runs collapse to one space, and matching is case-sensitive. A fact with more than 10 quotes, or any quote not found, fails.
+- **Diagnostics.** `grounding_missing` (reasons `no_evidence`, `evidence_too_short`) and `grounding_failed` (reasons `quote_not_found`, `too_many_quotes`), one per fact, with the new fact's `factId`. Quotes are never included.
+- **`upsertGraph`** nodes are host-supplied and never grounded.
+- **Librarian and heal** synthesize across events, so their pass rates are unknown. Measure them on your own event log before opting them in.
+- Evidence quotes are not stored.
+
 ## Pluggable Vector Retrieval
 
 When your entity corpus grows, in-process cosine similarity scoring becomes a bottleneck. The optional **`VectorRanker`** interface lets you delegate semantic ranking to [**sqlite-vec**](https://github.com/asg017/sqlite-vec), [**sqlite-vss**](https://github.com/asg017/sqlite-vss), or an external vector database while `WikiMemory` handles embedding validation, hybrid scoring, and tier-2 row hydration.
@@ -799,6 +829,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).