@equationalapplications/expo-llm-wiki 4.15.3 → 4.17.0

package/README.md

@@ -18,7 +18,8 @@ Local-first LLM memory for Expo and React Native. Combines the core semantic sea
 - **Retrieval tuning** — Per-call overrides for search behavior (pre-filter, hybrid blend, tier weights)
 - **Multi-entity reads** — Search across multiple `entity_id` namespaces in one pass with `tierWeights`
 - **Source provenance** — `WikiFact.source_type` distinguishes immutable document facts (`immutable_document`) from mutable derived/user facts. Immutable document content is protected from librarian/heal rewriting and only changed by `forget()` or re-ingest.
-- **React hooks** — `WikiProvider`, `useMemoryRead`, and all other hooks are re-exported directly from `@equationalapplications/expo-llm-wiki`
+- **Seeded ontologies** — Enforce strict taxonomies or allow emergent graph relationship extraction (`useOntologyManifest`, `useSetOntologyManifest`; Strict, Emergent, or Off; defaults to Off).
+- **React hooks** — `WikiProvider`, `useMemoryRead`, `useOntologyManifest`, `useSetOntologyManifest`, `useWikiTraversal`, and all other hooks re-exported from `@equationalapplications/expo-llm-wiki`
 - **Full-featured memory** — Facts, tasks, events, maintenance jobs (librarian, heal, reembed, prune)
 - **Interoperability:** Supports [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) import and export.
 
@@ -233,6 +234,73 @@ export function EntityLoadingSpinner({ entityId }: { entityId: string }) {
 }
 ```
 
+### `useOntologyManifest(entityId)`
+
+Reactive read — fetches on mount and when `entityId` or `wiki` changes:
+
+```typescript
+import { useOntologyManifest } from '@equationalapplications/expo-llm-wiki';
+
+const { manifest, mode, isPending, error, refetch } = useOntologyManifest('user-123');
+// manifest: OntologyManifest | null
+// mode: OntologyMode | null ('strict' | 'emergent' | 'off' when present)
+```
+
+Note: `manifest` and `mode` are `null` when the entity has no persisted or seeded manifest (`getOntologyManifest` returned `null`). Call `refetch()` after mutations to refresh.
+
+### `useSetOntologyManifest()`
+
+Mutation — same `{ execute, isPending, error, lastResult }` contract as `useWikiWrite`:
+
+```typescript
+import { useOntologyManifest, useSetOntologyManifest } from '@equationalapplications/expo-llm-wiki';
+
+export function OntologySettings({ entityId }: { entityId: string }) {
+  const { manifest, mode, refetch } = useOntologyManifest(entityId);
+  const { execute, isPending, error } = useSetOntologyManifest();
+
+  const handleSave = async () => {
+    await execute(entityId, {
+      node_types: [{ type: 'person', description: 'An individual.' }],
+      edge_types: [{
+        type: 'reports_to',
+        source_type: 'person',
+        target_type: 'person',
+        description: 'Reporting hierarchy.',
+      }],
+    }, { mode: 'strict' });
+    refetch();
+  };
+
+  // render manifest/mode; wire handleSave to a save button
+}
+```
+
+Global defaults and `seedManifests` bootstrap are configured at construction time via `createWiki(..., { config: { ontology: ... } })`. See the [core package README § Per-Entity Seeded Ontology](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/core/README.md#per-entity-seeded-ontology) for mode semantics and manifest schema.
+
+`useSetOntologyManifest` does not automatically refresh `useOntologyManifest` — call `refetch()` after a successful `execute()`, same as `useWikiWrite` + `useMemoryRead`.
+
+### `useWikiTraversal(entityId, options)`
+
+Reactive read — fetches on mount and whenever `entityId` or `options` change. Walks the knowledge graph N hops outward from a fact (`options.sourceId`) using edges written by `runLibrarian()`/`ingestDocument()`'s Seeded Ontology extraction pass:
+
+```typescript
+import { useWikiTraversal, formatGraphContext } from '@equationalapplications/expo-llm-wiki';
+
+const { nodes, edges, isPending, error, refetch } = useWikiTraversal('user-123', {
+  sourceId: 'fact_42',
+  maxDepth: 2,
+  direction: 'both',
+});
+
+const promptContext = formatGraphContext({ nodes, edges });
+```
+
+- `maxDepth` is clamped to `[1, 3]` regardless of input.
+- `edgeTypes: []` (explicit empty array) matches nothing; omitting it matches all edge types.
+- Defaults (`maxTraversalNodes`, `minTraversalConfidence`, `traversalDirection`, `excludeSourceTypes`) can be set globally via `createWiki(..., { config: { maxTraversalNodes: 20, ... } })` and overridden per-call.
+- `formatGraphContext()` is a pure function — call it with the hook's `{ nodes, edges }` to get a dense text block suitable for prompt injection.
+
 ## Component Lifecycle
 
 ```mermaid
@@ -244,6 +312,8 @@ flowchart TD
     C -->|"useWikiIngest()"| F["[Ingest Document]"]
     C -->|"useWikiForget()"| G["[Delete Memory]"]
     C -->|"useWikiMaintenance()"| H["[Run Jobs]"]
+    C -->|"useOntologyManifest(entityId)"| S["[Read Ontology]"]
+    C -->|"useSetOntologyManifest()"| T["[Update Ontology]"]
     D --> I{"entityId, query, wiki,<br/>or ReadOptions changed?"}
     I -->|"Yes"| J["Auto-refetch"]
     I -->|"No"| K["Return cached data"]
@@ -252,10 +322,17 @@ flowchart TD
     M --> N["Phase 1: Score facts<br/>Phase 2: Fetch winners"]
     N --> O["Update component state"]
     O --> P["Re-render with data"]
+    S --> I2{"entityId or wiki changed?"}
+    I2 -->|"Yes"| J2["Auto-refetch"]
+    I2 -->|"No"| K2["Return cached manifest/mode"]
+    J2 --> L2["Trigger getOntologyManifest()"]
+    L2 --> O2["Update component state"]
+    O2 --> P2["Re-render with manifest/mode"]
     E --> Q["Execute write()"]
     F --> Q
     G --> Q
     H --> Q
+    T --> Q
     Q --> R["Write completes"]
 ```
 
@@ -263,8 +340,10 @@ flowchart TD
 1. **Wrap app** with `<WikiProvider wiki={wiki}>` — provides wiki context
 2. **Use hooks** in components — access memory reactively
 3. **Read operations** auto-refetch when `entityId`, `query`, `wiki`, or `ReadOptions` values change; call `refetch()` to refresh manually
-4. **Write operations** (write, ingest, forget, maintenance) do not automatically re-trigger `useMemoryRead`; call `refetch()` after a write to refresh read results
-5. **Re-render** with new data flowing back to UI
+4. **Ontology reads** auto-refetch when `entityId` or `wiki` changes; call `refetch()` manually after ontology mutations
+5. **Write operations** (write, ingest, forget, maintenance) do not automatically re-trigger `useMemoryRead`; call `refetch()` after a write to refresh read results
+6. **Ontology writes** (`useSetOntologyManifest`) do not automatically re-trigger `useOntologyManifest` in the same component unless `refetch()` is called after `execute()` succeeds
+7. **Re-render** with new data flowing back to UI
 
 ## Retrieval Engine Internals
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equationalapplications/expo-llm-wiki",
-  "version": "4.15.3",
+  "version": "4.17.0",
   "description": "Local-first LLM memory for Expo and React Native. Combines the core semantic search and extraction engine with expo-sqlite and ready-to-use React hooks.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -55,8 +55,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@equationalapplications/react-llm-wiki": "4.15.3",
-    "@equationalapplications/core-llm-wiki": "4.15.3"
+    "@equationalapplications/core-llm-wiki": "4.17.0",
+    "@equationalapplications/react-llm-wiki": "4.17.0"
   },
   "peerDependencies": {
     "expo-sqlite": "^14.0.0 || ^15.0.0 || ^55.0.0 || ^56.0.0",