wiki-graph-sdk 0.8.0 → 0.8.2

package/dist/index.cjs

@@ -61,6 +61,7 @@ __export(src_exports, {
   createEntryRuntimeContext: () => createEntryRuntimeContext,
   createGenerationPerformanceHints: () => createGenerationPerformanceHints,
   createNodeTemplateEnvironment: () => createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform: () => createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage: () => createNodeWikiGraphStorage,
   createStageLLM: () => createStageLLM,
   createWikiGraphSDK: () => createWikiGraphSDK,
@@ -75,15 +76,20 @@ __export(src_exports, {
   formatLocatedChapterSourceCollectionUri: () => import_wiki_graph_core19.formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri: () => import_wiki_graph_core19.formatLocatedChapterUri,
   formatLocatedWikiGraphUri: () => import_wiki_graph_core19.formatLocatedWikiGraphUri,
+  formatSourceArtifactUri: () => import_wiki_graph_core19.formatSourceArtifactUri,
+  formatSourceLocatorFragment: () => import_wiki_graph_core19.formatSourceLocatorFragment,
   formatWikiGraphCommandUri: () => import_wiki_graph_core19.formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri: () => import_wiki_graph_core19.formatWikiGraphLibraryUri,
   getNodeResourcePath: () => getNodeResourcePath,
+  getWikiGraphSDKProviders: () => getWikiGraphSDKProviders,
   getWikiGraphSDKRuntimeContext: () => getWikiGraphSDKRuntimeContext,
   getWikiGraphSDKStateDir: () => getWikiGraphSDKStateDir,
   inspectWikiGraphArchive: () => inspectWikiGraphArchive,
   installNodeWikiGraphPlatform: () => installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri: () => import_wiki_graph_core19.isSourceLocatorScopeUri,
+  isWikiGraphJobUri: () => import_wiki_graph_core19.isWikiGraphJobUri,
   isWikiGraphLibraryUri: () => import_wiki_graph_core19.isWikiGraphLibraryUri,
+  isWikiGraphUri: () => import_wiki_graph_core19.isWikiGraphUri,
   loadRequiredStageConfig: () => loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig: () => loadWikiGraphRuntimeConfig,
   maskLocalConfigSection: () => maskLocalConfigSection,
@@ -95,6 +101,7 @@ __export(src_exports, {
   parseChapterUriPath: () => import_wiki_graph_core19.parseChapterUriPath,
   parseLocalConfigSection: () => parseLocalConfigSection,
   parseLocatedWikiGraphUri: () => import_wiki_graph_core19.parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment: () => import_wiki_graph_core19.parseSourceLocatorFragment,
   parseSourceTextJsonl: () => import_wiki_graph_core19.parseSourceTextJsonl,
   parseWikiGraphLibraryUri: () => import_wiki_graph_core19.parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax: () => import_wiki_graph_core19.parseWikiGraphUriSyntax,
@@ -103,10 +110,14 @@ __export(src_exports, {
   readLocalConfigSection: () => readLocalConfigSection,
   readWikiGraphEmbeddingConfig: () => readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection: () => replaceLocalConfigSection,
+  requireArchiveUri: () => import_wiki_graph_core19.requireArchiveUri,
   requireKnowledgeGraphWikispineConfig: () => requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri: () => import_wiki_graph_core19.requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri: () => import_wiki_graph_core19.requireLocatedObjectUri,
   resolveExtractionPrompt: () => import_wiki_graph_core10.resolveExtractionPrompt,
   resolveHostedProviderEndpoint: () => resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt: () => import_wiki_graph_core10.resolveKnowledgeGraphRecallPrompt,
+  resolveWikiGraphLLMJSON: () => resolveWikiGraphLLMJSON,
   resolveWikispineConfig: () => resolveWikispineConfig,
   runWikiGraphQueueWorker: () => runWikiGraphQueueWorker,
   validateLocalConfigSection: () => validateLocalConfigSection,
@@ -834,6 +845,9 @@ var nodeWikiGraphPlatform = {
     write: writeNodeZip
   }
 };
+function createNodeWikiGraphPlatform(options = {}) {
+  return options.lifecycle === void 0 ? nodeWikiGraphPlatform : { ...nodeWikiGraphPlatform, lifecycle: options.lifecycle };
+}
 var NodeTemplateLoader = class extends import_nunjucks.Loader {
   #dataDirectory;
   constructor(dataDirectory) {
@@ -879,10 +893,15 @@ function resolveNodeDataDirectory() {
     directory = parent;
   }
 }
-function createNodeWikiGraphStorage(stateRoot = pathModule.join(os.homedir(), ".wikigraph")) {
+function createNodeWikiGraphStorage(stateRootOrOptions = pathModule.join(
+  os.homedir(),
+  ".wikigraph"
+)) {
+  const libraryRoot = typeof stateRootOrOptions === "string" ? stateRootOrOptions : stateRootOrOptions.libraryRoot;
+  const documentStoreRoot = typeof stateRootOrOptions === "string" ? pathModule.join(stateRootOrOptions, "documents") : stateRootOrOptions.documentStoreRoot;
   return {
-    library: new NodeDirectory(stateRoot),
-    documentStore: new NodeDirectory(pathModule.join(stateRoot, "documents"))
+    library: new NodeDirectory(libraryRoot),
+    documentStore: new NodeDirectory(documentStoreRoot)
   };
 }
 function installNodeWikiGraphPlatform(stateRoot) {
@@ -890,7 +909,11 @@ function installNodeWikiGraphPlatform(stateRoot) {
   (0, import_platform.installWikiGraphStorage)(createNodeWikiGraphStorage(stateRoot));
 }
 function ensureNodeWikiGraphPlatform() {
-  (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
+  try {
+    (0, import_platform.getWikiGraphPlatform)();
+  } catch {
+    (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
+  }
   try {
     (0, import_platform.getWikiGraphStorage)();
   } catch {
@@ -936,12 +959,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");
@@ -1242,8 +1269,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")
@@ -1439,6 +1466,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");
@@ -1663,12 +1698,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,
@@ -1981,6 +2022,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;
@@ -2226,13 +2269,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 }
@@ -2340,6 +2385,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),
@@ -2530,6 +2582,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, {
@@ -2538,19 +2593,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 }
         });
       },
@@ -2562,6 +2620,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, {
@@ -2570,19 +2631,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 }
         });
       },
@@ -2616,6 +2680,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(
@@ -2686,11 +2768,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(
@@ -2699,6 +2790,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 };
@@ -3078,6 +3182,7 @@ var WikiGraphContinuationManager = class {
   }
 };
 async function continueArchiveCursor(cursor, limit) {
+  const embeddingProvider = cursor.kind === "evidence" || cursor.kind === "related" ? await resolveCursorEmbeddingProvider(cursor) : void 0;
   const location = await resolveWikiGraphArchiveLocation(
     archiveTargetFromLogicalLocator(getCursorArchivePath(cursor))
   );
@@ -3107,6 +3212,8 @@ async function continueArchiveCursor(cursor, limit) {
             limit,
             order: cursor.order,
             ...cursor.query === void 0 ? {} : { query: cursor.query },
+            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
             ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
             ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
           });
@@ -3118,6 +3225,8 @@ async function continueArchiveCursor(cursor, limit) {
             limit,
             order: cursor.order,
             ...cursor.query === void 0 ? {} : { query: cursor.query },
+            ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+            ...embeddingProvider === void 0 ? {} : { embeddingProvider },
             ...cursor.role === void 0 ? {} : { role: cursor.role },
             ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
             ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
@@ -3127,6 +3236,7 @@ async function continueArchiveCursor(cursor, limit) {
   );
 }
 async function continueLibraryCursor(cursor, limit) {
+  const embeddingProvider = cursor.kind === "evidence" || cursor.kind === "related" ? await resolveCursorEmbeddingProvider(cursor) : void 0;
   if (cursor.kind === "source-locators") {
     throw new Error(
       "Source locator cursors do not use the aggregate library index."
@@ -3163,6 +3273,8 @@ async function continueLibraryCursor(cursor, limit) {
         limit,
         order: cursor.order,
         ...cursor.query === void 0 ? {} : { query: cursor.query },
+        ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+        ...embeddingProvider === void 0 ? {} : { embeddingProvider },
         ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
         ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
       });
@@ -3176,6 +3288,8 @@ async function continueLibraryCursor(cursor, limit) {
           limit,
           order: cursor.order,
           ...cursor.query === void 0 ? {} : { query: cursor.query },
+          ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...cursor.role === void 0 ? {} : { role: cursor.role },
           ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
           ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext }
@@ -3200,7 +3314,7 @@ function createCollectionOptions(cursor, limit) {
   };
 }
 async function createFindOptions(cursor, limit) {
-  const embeddingProvider = await createConfiguredEmbeddingProvider();
+  const embeddingProvider = await resolveCursorEmbeddingProvider(cursor);
   return {
     archiveKey: cursor.archiveKey,
     ...cursor.backlinks === void 0 ? {} : { backlinks: cursor.backlinks },
@@ -3208,6 +3322,9 @@ async function createFindOptions(cursor, limit) {
     cursor: cursor.cursor,
     ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
     limit,
+    ...cursor.match === void 0 ? {} : { match: cursor.match },
+    ...cursor.order === void 0 ? {} : { order: cursor.order },
+    ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
     ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
     ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext },
     ...cursor.triplePattern === void 0 ? {} : { triplePattern: cursor.triplePattern },
@@ -3257,6 +3374,7 @@ function createContinuationPayload(context, cursor) {
         kind: "evidence",
         order: context.order ?? "doc-asc",
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
         targetUri: requireTargetUri(context, "Evidence")
@@ -3273,6 +3391,7 @@ function createContinuationPayload(context, cursor) {
         kind: "related",
         order: context.order ?? "doc-asc",
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.role === void 0 ? {} : { role: context.role },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
@@ -3308,7 +3427,10 @@ function createContinuationPayload(context, cursor) {
         indexScope: context.indexScope,
         kind: "search",
         ...createLibraryQueryPayload(context),
+        ...context.match === void 0 ? {} : { match: context.match },
+        ...context.order === void 0 ? {} : { order: context.order },
         ...context.query === void 0 ? {} : { query: context.query },
+        ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
         ...context.sourceContext === void 0 ? {} : { sourceContext: context.sourceContext },
         ...context.triplePattern === void 0 ? {} : { triplePattern: context.triplePattern },
@@ -3316,6 +3438,17 @@ function createContinuationPayload(context, cursor) {
       };
   }
 }
+async function resolveCursorEmbeddingProvider(cursor) {
+  if (cursor.kind !== "search" && cursor.query === void 0) return void 0;
+  if (cursor.queryMode === "fts") return void 0;
+  const provider = await createConfiguredEmbeddingProvider();
+  if (cursor.queryMode === "embedding" && provider === void 0) {
+    throw new Error(
+      "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
+    );
+  }
+  return provider;
+}
 function requireTargetUri(context, label) {
   if (context.targetUri !== void 0) return context.targetUri;
   throw new Error(`${label} continuation cursors require a target URI.`);
@@ -3339,7 +3472,10 @@ var import_wiki_graph_core10 = require("wiki-graph-core");
 var import_wiki_graph_core11 = require("wiki-graph-core");
 var import_wiki_graph_core12 = require("wiki-graph-core");
 function createStageLLM(config, options) {
-  const llmOptions = buildWikiGraphLLMOptions(config);
+  const llmOptions = options?.provider === void 0 ? buildWikiGraphLLMOptions(config) : {
+    ...config.concurrent?.request === void 0 ? {} : { concurrent: config.concurrent.request },
+    streamProvider: options.provider
+  };
   return new import_wiki_graph_core12.LLM({
     sampling: (0, import_wiki_graph_core11.createDefaultWikiGraphSampling)({
       ...llmOptions.temperature === void 0 ? {} : { temperature: llmOptions.temperature },
@@ -3353,10 +3489,13 @@ function createStageLLM(config, options) {
   });
 }
 async function loadRequiredStageConfig(options) {
+  const injected = options.llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
   const config = await loadWikiGraphRuntimeConfig({
-    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
+    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON },
+    ...options.llmJSON === void 0 && injected !== void 0 ? { skipLLMConfig: true } : {},
+    ...getWikiGraphSDKProviders().embedding === void 0 ? {} : { skipEmbeddingConfig: true }
   });
-  if (config.llm?.provider === void 0 || config.llm.model === void 0) {
+  if (injected === void 0 && (config.llm?.provider === void 0 || config.llm.model === void 0)) {
     throw new Error(
       "Missing LLM configuration. Set --llm for one run, or configure `wikg://local/config/llm` with provider and model."
     );
@@ -3492,19 +3631,52 @@ function getGenerationPlanningProfile(task) {
 // src/worker.ts
 var import_worker = require("wiki-graph-core/worker");
 var import_wiki_graph_core13 = require("wiki-graph-core");
+
+// src/host.ts
+var import_platform2 = require("wiki-graph-core/platform");
+function prepareWikiGraphSDKHost(host) {
+  if (host?.platform === void 0) {
+    ensureNodeWikiGraphPlatform();
+    return;
+  }
+  (0, import_platform2.installWikiGraphPlatform)(host.platform);
+}
+function assertWikiGraphSDKHostOptions(options) {
+  if (options.host?.storage !== void 0 && options.stateDir !== void 0) {
+    throw new TypeError(
+      "Wiki Graph SDK host.storage and stateDir cannot be used together."
+    );
+  }
+}
+async function withWikiGraphSDKHost(options, operation) {
+  assertWikiGraphSDKHostOptions(options);
+  prepareWikiGraphSDKHost(options.host);
+  if (options.host?.storage !== void 0) {
+    return await (0, import_platform2.withWikiGraphStorage)(options.host.storage, operation);
+  }
+  return await withNodeWikiGraphStorage(options.stateDir, operation);
+}
+
+// src/worker.ts
 var import_worker2 = require("wiki-graph-core/worker");
 async function runBuildJobWorker(options) {
-  installNodeWikiGraphPlatform();
-  const { stateDir, ...coreOptions } = options;
-  await withNodeWikiGraphStorage(
-    stateDir,
+  const { host, stateDir, ...coreOptions } = options;
+  await withWikiGraphSDKHost(
+    {
+      ...host === void 0 ? {} : { host },
+      ...stateDir === void 0 ? {} : { stateDir }
+    },
     async () => await (0, import_worker.runBuildJobWorker)(coreOptions)
   );
 }
 
 // src/default-worker.ts
 async function runWikiGraphQueueWorker(options = {}) {
-  const config = await loadWikiGraphRuntimeConfig();
+  const providers = getWikiGraphSDKProviders();
+  const config = await loadWikiGraphRuntimeConfig({
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...providers.llm === void 0 ? {} : { skipLLMConfig: true }
+  });
   await runBuildJobWorker({
     concurrency: config.concurrent?.job ?? DEFAULT_GENERATION_JOB_CONCURRENCY,
     executeJob: async (job, reporter, context) => {
@@ -3513,12 +3685,16 @@ async function runWikiGraphQueueWorker(options = {}) {
         async () => await executeBuildJob(job, reporter, context)
       );
     },
+    ...options.idleTimeoutMs === void 0 ? {} : { idleTimeoutMs: options.idleTimeoutMs },
     ...options.signal === void 0 ? {} : { signal: options.signal }
   });
 }
 async function executeBuildJob(job, reporter, context) {
+  const providers = getWikiGraphSDKProviders();
   const config = await loadWikiGraphRuntimeConfig({
-    ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON }
+    ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON },
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...job.llmJSON === void 0 && providers.llm !== void 0 ? { skipLLMConfig: true } : {}
   });
   const execution = await openJobExecutor(
     job,
@@ -3653,12 +3829,17 @@ async function openJobExecutor(job, config, signal, reporter) {
   const stageConfig = generation ? await loadRequiredStageConfig({
     ...job.llmJSON === void 0 ? {} : { llmJSON: job.llmJSON }
   }) : void 0;
+  const injectedLLM = job.llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
   const llm = stageConfig === void 0 ? void 0 : createStageLLM(stageConfig, {
     cacheDirectory: job.cache,
     logDirectory: job.log,
     onTokenUsage: async (usage) => {
       await reporter.addTokenUsage(usage);
-    }
+    },
+    onStreamProgress: async ({ outputCharacters }) => {
+      await reporter.addOutputCharacters(outputCharacters);
+    },
+    ...injectedLLM === void 0 ? {} : { provider: injectedLLM }
   });
   const promptSource = job.prompt ?? stageConfig?.prompt;
   const wikispine = job.target === "knowledge-graph" ? requireKnowledgeGraphWikispineConfig(config) : void 0;
@@ -3679,7 +3860,7 @@ async function openJobExecutor(job, config, signal, reporter) {
         "Local Wikimedia resolution requires an LLM."
       ),
       llmModelId: requireValue(
-        stageConfig?.llm?.model,
+        stageConfig?.llm?.model ?? injectedLLM?.model,
         "Local Wikimedia resolution requires an LLM model."
       )
     } : {
@@ -3688,7 +3869,7 @@ async function openJobExecutor(job, config, signal, reporter) {
       token: config.wikimedia.token
     }
   );
-  const embeddingProvider = job.target === "index-embedding-source" || job.target === "index-embedding-summary" ? buildSearchIndexEmbeddingProvider(requireEmbeddingConfig(config)) : void 0;
+  const embeddingProvider = job.target === "index-embedding-source" || job.target === "index-embedding-summary" ? getWikiGraphSDKProviders().embedding ?? buildSearchIndexEmbeddingProvider(requireEmbeddingConfig(config)) : void 0;
   return {
     async close() {
       await wikimediaResolver?.close();
@@ -3881,6 +4062,12 @@ var WikiGraphJobManager = class {
   async clean() {
     return await this.#runtime.run(async () => await (0, import_wiki_graph_core15.cleanBuildJobs)());
   }
+  async runWorker(options = {}) {
+    await this.#runtime.run(
+      async () => await runWikiGraphQueueWorker(options),
+      options.signal
+    );
+  }
   async get(jobId) {
     return await this.#runtime.run(
       async () => await this.#createHandle(await this.#backend.get(jobId))
@@ -3956,12 +4143,13 @@ var WikiGraphJobManager = class {
   }
   async enqueue(options) {
     return await this.#runtime.run(async () => {
+      const llmJSON = resolveWikiGraphLLMJSON(options);
       const location = await resolveWikiGraphArchiveLocation(options.archive);
       return await (0, import_wiki_graph_core15.withArchiveBuildJobCreationLock)(
         location.archiveFile,
         async () => {
           const target = options.target ?? "reading-summary";
-          await validateQueueTargetConfig(target, options.llmJSON);
+          await validateQueueTargetConfig(target, llmJSON);
           const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
           const candidates = await new import_wiki_graph_core15.WikiGraphArchiveFile(
             location.archiveFile
@@ -4011,7 +4199,7 @@ var WikiGraphJobManager = class {
                     archive: location.archiveFile,
                     boost: options.boost ?? false,
                     chapterId: candidate.chapter.chapterId,
-                    ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON },
+                    ...llmJSON === void 0 ? {} : { llmJSON },
                     ...options.prompt === void 0 ? {} : { prompt: options.prompt },
                     target
                   }),
@@ -4033,9 +4221,10 @@ var WikiGraphJobManager = class {
   }
   async planEnqueue(options) {
     return await this.#runtime.run(async () => {
+      const llmJSON = resolveWikiGraphLLMJSON(options);
       const location = await resolveWikiGraphArchiveLocation(options.archive);
       const target = options.target ?? "reading-summary";
-      await validateQueueTargetConfig(target, options.llmJSON);
+      await validateQueueTargetConfig(target, llmJSON);
       const selectedExplicitly = options.chapterId !== void 0 || options.chapterIds !== void 0 || options.chapterPath !== void 0 || options.depth !== void 0;
       const candidates = await new import_wiki_graph_core15.WikiGraphArchiveFile(
         location.archiveFile
@@ -4280,12 +4469,15 @@ async function selectQueueChapters(document, chapters, options) {
   );
 }
 async function validateQueueTargetConfig(target, llmJSON) {
+  const providers = getWikiGraphSDKProviders();
   const config = target === "knowledge-graph" || target === "reading-graph" || target === "reading-summary" ? await loadRequiredStageConfig({
     ...llmJSON === void 0 ? {} : { llmJSON }
   }) : await loadWikiGraphRuntimeConfig({
-    ...llmJSON === void 0 ? {} : { llmJSON }
+    ...llmJSON === void 0 ? {} : { llmJSON },
+    ...providers.embedding === void 0 ? {} : { skipEmbeddingConfig: true },
+    ...llmJSON === void 0 && providers.llm !== void 0 ? { skipLLMConfig: true } : {}
   });
-  if ((target === "index-embedding-source" || target === "index-embedding-summary") && config.embedding === void 0) {
+  if ((target === "index-embedding-source" || target === "index-embedding-summary") && config.embedding === void 0 && providers.embedding === void 0) {
     throw new Error(
       "Missing embeddings configuration. Configure `wikg://local/config/embeddings` before queueing embedding index artifact jobs."
     );
@@ -4365,6 +4557,16 @@ function forwardAbort(source, target) {
 // src/libraries.ts
 var import_wiki_graph_core16 = require("wiki-graph-core");
 var import_promises5 = require("fs/promises");
+async function resolveQueryEmbeddingProvider(queryMode) {
+  if (queryMode === "fts") return void 0;
+  const provider = await createConfiguredEmbeddingProvider();
+  if (queryMode === "embedding" && provider === void 0) {
+    throw new Error(
+      "Embedding query mode requires embeddings configuration at `wikg://local/config/embeddings`."
+    );
+  }
+  return provider;
+}
 var WikiGraphLibraryManager = class {
   #runtime;
   constructor(runtime) {
@@ -4434,6 +4636,43 @@ var WikiGraphLibraryManager = class {
       )
     );
   }
+  async readArchive(target, consume, options = {}) {
+    return await this.#runtime.run(async () => {
+      const parsedTarget = requireLibraryArchiveTarget(target);
+      const library = await (0, import_wiki_graph_core16.resolveWikiGraphLibrary)(parsedTarget);
+      return await (0, import_wiki_graph_core16.withWikiGraphLibraryLock)(
+        library.id,
+        "read",
+        async () => {
+          throwIfAborted(options.signal);
+          const archive = await (0, import_wiki_graph_core16.getWikiGraphLibraryArchive)(parsedTarget);
+          const file = requireReadableLibraryArchiveFile(archive);
+          const reader = await file.openReader();
+          let active = true;
+          try {
+            const content = {
+              mediaType: "application/vnd.wiki-graph.archive",
+              size: reader.size,
+              stream: createCallbackScopedArchiveStream(
+                reader,
+                () => active,
+                options.signal
+              ),
+              uri: archive.uri
+            };
+            return await runAbortableCallback(
+              async () => await consume(content),
+              options.signal
+            );
+          } finally {
+            active = false;
+            await reader.close();
+          }
+        },
+        options.signal === void 0 ? {} : { signal: options.signal }
+      );
+    }, options.signal);
+  }
   async moveArchive(options) {
     return toArchiveSnapshot(
       await this.#runtime.run(
@@ -4523,7 +4762,9 @@ var WikiGraphLibraryManager = class {
   }
   async search(target, query, options = {}) {
     return await this.#runtime.run(async () => {
-      const embeddingProvider = await createConfiguredEmbeddingProvider();
+      const embeddingProvider = await resolveQueryEmbeddingProvider(
+        options.queryMode
+      );
       return await (0, import_wiki_graph_core16.findWikiGraphLibraryObjects)(
         requireLibraryTarget(target),
         query,
@@ -4536,7 +4777,9 @@ var WikiGraphLibraryManager = class {
   }
   async searchArchiveMembers(target, query, options = {}) {
     return await this.#runtime.run(async () => {
-      const embeddingProvider = await createConfiguredEmbeddingProvider();
+      const embeddingProvider = await resolveQueryEmbeddingProvider(
+        options.queryMode
+      );
       return await (0, import_wiki_graph_core16.findWikiGraphLibraryArchiveMembers)(
         requireLibraryTarget(target),
         query,
@@ -4577,22 +4820,36 @@ var WikiGraphLibraryManager = class {
     );
   }
   async related(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await (0, import_wiki_graph_core16.listRelatedWikiGraphLibraryObjects)(
+    return await this.#runtime.run(async () => {
+      if (options.query === void 0 && options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
+      const embeddingProvider = options.query === void 0 ? void 0 : await resolveQueryEmbeddingProvider(options.queryMode);
+      return await (0, import_wiki_graph_core16.listRelatedWikiGraphLibraryObjects)(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async evidence(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await (0, import_wiki_graph_core16.listWikiGraphLibraryEvidence)(
+    return await this.#runtime.run(async () => {
+      if (options.query === void 0 && options.queryMode !== void 0) {
+        throw new Error("`queryMode` requires `query`.");
+      }
+      const embeddingProvider = options.query === void 0 ? void 0 : await resolveQueryEmbeddingProvider(options.queryMode);
+      return await (0, import_wiki_graph_core16.listWikiGraphLibraryEvidence)(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async pack(target, objectUri, budget = 5e3) {
     return await this.#runtime.run(
@@ -4674,6 +4931,97 @@ function requireLibraryTarget(value) {
   }
   return target;
 }
+function requireLibraryArchiveTarget(value) {
+  const target = requireLibraryTarget(value);
+  if (target.kind !== "archive" || target.archivePublicId === void 0 || target.objectUri !== void 0) {
+    throw new TypeError("Expected a Wiki Graph library archive URI.");
+  }
+  return target;
+}
+function requireReadableLibraryArchiveFile(archive) {
+  if (!archive.exists || archive.status === "missing") {
+    throw new Error(`Wiki Graph library archive is missing: ${archive.uri}`);
+  }
+  if (archive.status === "conflict") {
+    throw new Error(
+      `Wiki Graph library archive has a conflict and cannot be read: ${archive.uri}`
+    );
+  }
+  if (archive.file === void 0) {
+    throw new Error(
+      `Wiki Graph library archive is unavailable: ${archive.uri}`
+    );
+  }
+  return archive.file;
+}
+var ARCHIVE_STREAM_CHUNK_SIZE = 64 * 1024;
+function createCallbackScopedArchiveStream(reader, isActive, signal) {
+  let consumed = false;
+  return {
+    [Symbol.asyncIterator]() {
+      assertArchiveReadSessionActive(isActive, signal);
+      if (consumed) {
+        throw new Error(
+          "The library archive stream has already been consumed."
+        );
+      }
+      consumed = true;
+      let offset = 0;
+      let finished = false;
+      return {
+        async next() {
+          if (finished) return { done: true, value: void 0 };
+          assertArchiveReadSessionActive(isActive, signal);
+          if (offset >= reader.size) {
+            finished = true;
+            return { done: true, value: void 0 };
+          }
+          const length = Math.min(
+            ARCHIVE_STREAM_CHUNK_SIZE,
+            reader.size - offset
+          );
+          const chunk = await reader.read(offset, length);
+          assertArchiveReadSessionActive(isActive, signal);
+          offset += chunk.byteLength;
+          return { done: false, value: chunk };
+        },
+        return() {
+          finished = true;
+          return Promise.resolve({ done: true, value: void 0 });
+        }
+      };
+    }
+  };
+}
+function assertArchiveReadSessionActive(isActive, signal) {
+  if (!isActive()) {
+    throw new Error(
+      "The library archive stream cannot be read after its callback has finished."
+    );
+  }
+  throwIfAborted(signal);
+}
+async function runAbortableCallback(operation, signal) {
+  if (signal === void 0) return await operation();
+  throwIfAborted(signal);
+  let rejectAbort;
+  const aborted = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => rejectAbort(abortReason(signal));
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await Promise.race([operation(), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted === true) throw abortReason(signal);
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
 
 // src/maintenance.ts
 var import_wiki_graph_core17 = require("wiki-graph-core");
@@ -4743,11 +5091,14 @@ var WikiGraphSDK = class {
   libraries;
   maintenance;
   constructor(options = {}) {
-    ensureNodeWikiGraphPlatform();
+    assertWikiGraphSDKHostOptions(options);
+    prepareWikiGraphSDKHost(options.host);
     this.#context = {
       cwd: options.cwd ?? process.cwd(),
       env: { ...process.env, ...options.env },
       envPolicy: options.envPolicy ?? "production",
+      ...options.host === void 0 ? {} : { host: options.host },
+      providers: { ...options.providers },
       ...options.stateDir === void 0 ? {} : { stateDir: options.stateDir }
     };
     this.archives = new WikiGraphArchiveManager(this);
@@ -4759,7 +5110,7 @@ var WikiGraphSDK = class {
     this.maintenance = new WikiGraphMaintenanceManager(this);
   }
   async run(operation, signal, options = {}) {
-    throwIfAborted(signal);
+    throwIfAborted2(signal);
     const runWithContext = async () => await withWikiGraphSDKRuntimeContext(this.#context, async () => {
       if (options.skipHomeBootstrap !== true) {
         this.#homeReady ??= (0, import_wiki_graph_core18.ensureWikiGraphHomeSchemaCurrent)().catch(
@@ -4772,18 +5123,21 @@ var WikiGraphSDK = class {
       }
       return await operation();
     });
-    const result = this.#context.stateDir === void 0 ? await runWithContext() : await withNodeWikiGraphStorage(
-      this.#context.stateDir,
+    const result = await withWikiGraphSDKHost(
+      {
+        ...this.#context.host === void 0 ? {} : { host: this.#context.host },
+        ...this.#context.stateDir === void 0 ? {} : { stateDir: this.#context.stateDir }
+      },
       runWithContext
     );
-    throwIfAborted(signal);
+    throwIfAborted2(signal);
     return result;
   }
   close() {
     this.jobs.close();
   }
 };
-function throwIfAborted(signal) {
+function throwIfAborted2(signal) {
   if (signal?.aborted !== true) return;
   throw signal.reason instanceof Error ? signal.reason : new Error("The Wiki Graph SDK operation was aborted.");
 }
@@ -4825,6 +5179,7 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
   createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
   createStageLLM,
   createWikiGraphSDK,
@@ -4839,15 +5194,20 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri,
   formatLocatedWikiGraphUri,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri,
   getNodeResourcePath,
+  getWikiGraphSDKProviders,
   getWikiGraphSDKRuntimeContext,
   getWikiGraphSDKStateDir,
   inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri,
+  isWikiGraphJobUri,
   isWikiGraphLibraryUri,
+  isWikiGraphUri,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,
@@ -4859,6 +5219,7 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   parseChapterUriPath,
   parseLocalConfigSection,
   parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -4867,10 +5228,14 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   readLocalConfigSection,
   readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection,
+  requireArchiveUri,
   requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri,
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,
+  resolveWikiGraphLLMJSON,
   resolveWikispineConfig,
   runWikiGraphQueueWorker,
   validateLocalConfigSection,