wiki-graph-sdk 0.8.0 → 0.8.2

package/README.md

@@ -23,6 +23,52 @@ for (const job of jobs) {
 wikiGraph.close();
 ```
 
+Electron and other Node hosts may provide their own lifecycle identity and
+storage layout without importing `wiki-graph-core`:
+
+```ts
+import {
+  createNodeWikiGraphPlatform,
+  createNodeWikiGraphStorage,
+  createWikiGraphSDK,
+} from "wiki-graph-sdk";
+
+const wikiGraph = createWikiGraphSDK({
+  host: {
+    platform: createNodeWikiGraphPlatform({ lifecycle }),
+    storage: createNodeWikiGraphStorage({
+      libraryRoot: "/path/to/home",
+      documentStoreRoot: "/path/to/documents",
+    }),
+  },
+});
+```
+
+Storage is scoped to the SDK instance. Platform services, including lifecycle,
+are process-wide; SDK instances in one process must use one compatible
+platform. `host.storage` and `stateDir` cannot be supplied together.
+
+Applications may replace the configured LLM and embedding implementations for
+one SDK instance:
+
+```ts
+const wikiGraph = createWikiGraphSDK({
+  providers: {
+    llm: myStreamingLLMProvider,
+    embedding: myEmbeddingProvider,
+  },
+});
+
+await wikiGraph.jobs.runWorker();
+```
+
+An operation-level `llm` option (the typed SDK equivalent of CLI `--llm`)
+takes precedence over the injected LLM provider. An injected provider takes
+precedence over local database configuration. Injected objects are
+process-local and are not persisted with durable jobs, so a worker in another
+process must create its SDK with the same providers. The standalone default
+worker continues to use local configuration.
+
 Job event subscriptions observe durable work without coupling observation to
 cancellation. Call `job.cancel()` explicitly to cancel a job; unsubscribing
 only stops the current listener.

package/dist/archives.cjs

@@ -826,12 +826,16 @@ function getWikiGraphSDKRuntimeContext() {
   return runtimeContext.getStore() ?? {
     cwd: process.cwd(),
     env: process.env,
-    envPolicy: "production"
+    envPolicy: "production",
+    providers: {}
   };
 }
 function getWikiGraphSDKStateDir() {
   return getWikiGraphSDKRuntimeContext().stateDir;
 }
+function getWikiGraphSDKProviders() {
+  return getWikiGraphSDKRuntimeContext().providers ?? {};
+}
 
 // src/local-config.ts
 var import_path = require("path");
@@ -1049,8 +1053,8 @@ var inlineLLMConfigSchema = import_zod.z.object({
 });
 async function loadWikiGraphRuntimeConfig(options) {
   const [embedding, localLLM, concurrent, wikimedia, wikispine] = await Promise.all([
-    readLocalConfigSection("embeddings"),
-    readLocalConfigSection("llm"),
+    options?.skipEmbeddingConfig === true ? Promise.resolve({}) : readLocalConfigSection("embeddings"),
+    options?.skipLLMConfig === true ? Promise.resolve({}) : readLocalConfigSection("llm"),
     readLocalConfigSection("concurrent"),
     readLocalConfigSection("wikimedia"),
     readLocalConfigSection("wikispine")
@@ -1246,6 +1250,14 @@ function formatError2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/providers.ts
+function resolveWikiGraphLLMJSON(options) {
+  if (options.llm !== void 0 && options.llmJSON !== void 0) {
+    throw new Error("Pass either llm or llmJSON, not both.");
+  }
+  return options.llm === void 0 ? options.llmJSON : JSON.stringify(options.llm);
+}
+
 // src/runtime-path.ts
 var import_os2 = require("os");
 var import_path2 = require("path");
@@ -1440,12 +1452,18 @@ var WikiGraphConversionManager = class {
     }
     const requiresDigest = options.input.format !== "wikg";
     const requiresLLM = requiresDigest && targetStage !== "planned" && targetStage !== "sourced";
+    const llmJSON = resolveWikiGraphLLMJSON(options);
+    const injectedLLM = llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
     const config = await loadWikiGraphRuntimeConfig({
-      ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
+      ...llmJSON === void 0 ? {} : { llmJSON },
+      ...injectedLLM === void 0 ? {} : { skipLLMConfig: true },
+      ...getWikiGraphSDKProviders().embedding === void 0 ? {} : { skipEmbeddingConfig: true }
     });
     const app = new import_wiki_graph_core3.WikiGraph({
       ...options.verbose === true ? { verbose: true } : {},
-      ...requiresLLM ? { llm: buildWikiGraphLLMOptions(config) } : {}
+      ...requiresLLM ? {
+        llm: injectedLLM === void 0 ? buildWikiGraphLLMOptions(config) : { streamProvider: injectedLLM }
+      } : {}
     });
     const documentDirectory = await prepareDigestDirectory(
       options.digestDirectory,
@@ -1733,6 +1751,8 @@ function createOpenAICompatibleName2(baseURL) {
 
 // src/query-runtime.ts
 async function createConfiguredEmbeddingProvider() {
+  const injected = getWikiGraphSDKProviders().embedding;
+  if (injected !== void 0) return injected;
   const config = await readWikiGraphEmbeddingConfig();
   if (config.provider === void 0 || config.model === void 0 || config.provider === "openai-compatible" && config.baseURL === void 0 || config.provider === "openai" && config.baseURL !== void 0) {
     return void 0;
@@ -1978,13 +1998,15 @@ var WikiGraphArchiveHandle = class {
     );
   }
   async search(query, options = {}) {
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
@@ -2092,6 +2114,13 @@ var WikiGraphArchiveHandle = class {
     );
     return status;
   }
+  /** Clear cached search sessions without changing the archive index. */
+  async clearSearchSessions(options = {}) {
+    await this.#runtime.run(
+      async () => await (0, import_wiki_graph_core7.deleteArchiveSearchSessions)(this.path),
+      options.signal
+    );
+  }
   async listChapters(options = {}) {
     return await this.#readDocument(
       async (document) => await (0, import_wiki_graph_core7.listChapters)(document),
@@ -2282,6 +2311,9 @@ var WikiGraphArchiveHandle = class {
   }
   async related(objectUri = this.objectUri, options = {}) {
     if (options.query === void 0) {
+      if (options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await (0, import_wiki_graph_core7.listRelatedArchiveObjects)(document, objectUri, {
@@ -2290,19 +2322,22 @@ var WikiGraphArchiveHandle = class {
         });
       }, options);
     }
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
         return await (0, import_wiki_graph_core7.listRelatedArchiveObjects)(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2314,6 +2349,9 @@ var WikiGraphArchiveHandle = class {
   }
   async evidence(objectUri = this.objectUri, options = {}) {
     if (options.query === void 0) {
+      if (options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
       return await this.#readDocument(async (document) => {
         const chapters = await this.#resolveScope(document, {});
         return await (0, import_wiki_graph_core7.listArchiveEvidence)(document, objectUri, {
@@ -2322,19 +2360,22 @@ var WikiGraphArchiveHandle = class {
         });
       }, options);
     }
-    const embeddingProvider = await this.#runtime.run(
-      createConfiguredEmbeddingProvider,
+    const embeddingProvider = await this.#resolveQueryEmbeddingProvider(
+      options.queryMode,
       options.signal
     );
     return await this.#writeDocument(
       async (document) => {
-        const chapters = await this.#resolveQueryChapters(document, options);
+        const chapters = await this.#resolveQueryChapters(document, options, {
+          embeddingProvider
+        });
         await ensureArchiveSearchIndex(document, {
           ...chapters === void 0 ? {} : { chapters },
           ...embeddingProvider === void 0 ? {} : { embeddingProvider }
         });
         return await (0, import_wiki_graph_core7.listArchiveEvidence)(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2368,6 +2409,24 @@ var WikiGraphArchiveHandle = class {
       return meta;
     }, options);
   }
+  async setArchiveTitle(title, options = {}) {
+    const normalized = title?.trim() ?? null;
+    if (title !== null && normalized === "") {
+      throw new Error("Archive title cannot be empty.");
+    }
+    return await this.#writeDocument(async (document) => {
+      if (normalized === null) {
+        await document.metadata.deleteKey("", "title");
+      } else {
+        await document.metadata.put(
+          { kind: import_wiki_graph_core7.ObjectMetadataKind.Archive, objectPath: "" },
+          "title",
+          normalized
+        );
+      }
+      return normalized;
+    }, options);
+  }
   async readCover(options = {}) {
     const app = new import_wiki_graph_core7.WikiGraph({});
     return await this.#runtime.run(
@@ -2438,11 +2497,20 @@ var WikiGraphArchiveHandle = class {
     if (options.chapters !== void 0) return options.chapters;
     return (await resolveArchiveScope(document, this.objectUri, options.depth))?.chapterIds;
   }
-  async #resolveQueryChapters(document, options) {
+  async #resolveQueryChapters(document, options, capabilities) {
     const chapters = await this.#resolveScope(document, options);
-    if (options.skipUnindexed !== true) return chapters;
+    const coverageOptions = {
+      ...chapters === void 0 ? {} : { chapters },
+      ...capabilities.embeddingProvider === void 0 ? {} : { embeddingProvider: capabilities.embeddingProvider },
+      requireEmbeddingProvider: true,
+      ...options.queryMode === void 0 ? {} : { queryMode: options.queryMode }
+    };
+    if (options.skipUnindexed !== true) {
+      await (0, import_wiki_graph_core7.assertArchiveIndexArtifactsReady)(document, coverageOptions);
+      return chapters;
+    }
     const queryable = await (0, import_wiki_graph_core7.listArchiveQueryableChapterIds)(document, {
-      ...chapters === void 0 ? {} : { chapters }
+      ...coverageOptions
     });
     if (queryable.length === 0) {
       throw new Error(
@@ -2451,6 +2519,19 @@ var WikiGraphArchiveHandle = class {
     }
     return queryable;
   }
+  async #resolveQueryEmbeddingProvider(queryMode, signal) {
+    if (queryMode === "fts") return void 0;
+    const provider = await this.#runtime.run(
+      createConfiguredEmbeddingProvider,
+      signal
+    );
+    if (queryMode === "embedding" && provider === void 0) {
+      throw new Error(
+        "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
+      );
+    }
+    return provider;
+  }
 };
 async function ensureArchiveSearchIndex(document, options = {}) {
   const scope = options.chapters === void 0 ? {} : { chapters: options.chapters };