wiki-graph-sdk 0.8.0 → 0.8.2

package/dist/index.js

@@ -11,6 +11,7 @@ import { Readable as Readable2 } from "stream";
 import {
   addChapter,
   applyChapterTree,
+  assertArchiveIndexArtifactsReady,
   assertNoActiveBuildJobConflicts,
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
@@ -141,6 +142,7 @@ import * as yauzl from "yauzl";
 import * as yazl from "yazl";
 import { Environment, Loader } from "nunjucks";
 import {
+  getWikiGraphPlatform,
   getWikiGraphStorage,
   installWikiGraphPlatform,
   installWikiGraphStorage,
@@ -763,6 +765,9 @@ var nodeWikiGraphPlatform = {
     write: writeNodeZip
   }
 };
+function createNodeWikiGraphPlatform(options = {}) {
+  return options.lifecycle === void 0 ? nodeWikiGraphPlatform : { ...nodeWikiGraphPlatform, lifecycle: options.lifecycle };
+}
 var NodeTemplateLoader = class extends Loader {
   #dataDirectory;
   constructor(dataDirectory) {
@@ -808,10 +813,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) {
@@ -819,7 +829,11 @@ function installNodeWikiGraphPlatform(stateRoot) {
   installWikiGraphStorage(createNodeWikiGraphStorage(stateRoot));
 }
 function ensureNodeWikiGraphPlatform() {
-  installWikiGraphPlatform(nodeWikiGraphPlatform);
+  try {
+    getWikiGraphPlatform();
+  } catch {
+    installWikiGraphPlatform(nodeWikiGraphPlatform);
+  }
   try {
     getWikiGraphStorage();
   } catch {
@@ -865,12 +879,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
 import { join as join2 } from "path";
@@ -1171,8 +1189,8 @@ var inlineLLMConfigSchema = 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")
@@ -1368,6 +1386,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
 import { homedir as homedir3 } from "os";
 import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
@@ -1601,12 +1627,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 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,
@@ -1921,6 +1953,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;
@@ -2172,13 +2206,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 }
@@ -2286,6 +2322,13 @@ var WikiGraphArchiveHandle = class {
     );
     return status;
   }
+  /** Clear cached search sessions without changing the archive index. */
+  async clearSearchSessions(options = {}) {
+    await this.#runtime.run(
+      async () => await deleteArchiveSearchSessions(this.path),
+      options.signal
+    );
+  }
   async listChapters(options = {}) {
     return await this.#readDocument(
       async (document) => await listChapters2(document),
@@ -2476,6 +2519,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 listRelatedArchiveObjects(document, objectUri, {
@@ -2484,19 +2530,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 listRelatedArchiveObjects(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2508,6 +2557,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 listArchiveEvidence(document, objectUri, {
@@ -2516,19 +2568,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 listArchiveEvidence(document, objectUri, {
           ...withoutOperation(options),
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider },
           ...chapters === void 0 ? {} : { chapters }
         });
       },
@@ -2562,6 +2617,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: ObjectMetadataKind.Archive, objectPath: "" },
+          "title",
+          normalized
+        );
+      }
+      return normalized;
+    }, options);
+  }
   async readCover(options = {}) {
     const app = new WikiGraph2({});
     return await this.#runtime.run(
@@ -2632,11 +2705,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 assertArchiveIndexArtifactsReady(document, coverageOptions);
+      return chapters;
+    }
     const queryable = await listArchiveQueryableChapterIds(document, {
-      ...chapters === void 0 ? {} : { chapters }
+      ...coverageOptions
     });
     if (queryable.length === 0) {
       throw new Error(
@@ -2645,6 +2727,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 };
@@ -3040,6 +3135,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))
   );
@@ -3069,6 +3165,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 }
           });
@@ -3080,6 +3178,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 }
@@ -3089,6 +3189,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."
@@ -3125,6 +3226,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 }
       });
@@ -3138,6 +3241,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 }
@@ -3162,7 +3267,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 },
@@ -3170,6 +3275,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 },
@@ -3219,6 +3327,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")
@@ -3235,6 +3344,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 },
@@ -3270,7 +3380,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 },
@@ -3278,6 +3391,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.`);
@@ -3318,7 +3442,10 @@ import {
 import { createDefaultWikiGraphSampling } from "wiki-graph-core";
 import { LLM } from "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 LLM({
     sampling: createDefaultWikiGraphSampling({
       ...llmOptions.temperature === void 0 ? {} : { temperature: llmOptions.temperature },
@@ -3332,10 +3459,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."
     );
@@ -3478,23 +3608,59 @@ import {
   resolveChapterPathReadonly as resolveChapterPathReadonly2,
   WikiGraphArchiveFile as WikiGraphArchiveFile4
 } from "wiki-graph-core";
+
+// src/host.ts
+import {
+  installWikiGraphPlatform as installWikiGraphPlatform2,
+  withWikiGraphStorage as withWikiGraphStorage2
+} from "wiki-graph-core/platform";
+function prepareWikiGraphSDKHost(host) {
+  if (host?.platform === void 0) {
+    ensureNodeWikiGraphPlatform();
+    return;
+  }
+  installWikiGraphPlatform2(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 withWikiGraphStorage2(options.host.storage, operation);
+  }
+  return await withNodeWikiGraphStorage(options.stateDir, operation);
+}
+
+// src/worker.ts
 import {
   applyChapterJobArtifactFile as applyChapterJobArtifactFile2,
   createLocalChapterJobFileExecutor,
   writeChapterJobInputFile as writeChapterJobInputFile2
 } from "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 runCoreBuildJobWorker(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) => {
@@ -3503,12 +3669,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,
@@ -3643,12 +3813,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;
@@ -3669,7 +3844,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."
       )
     } : {
@@ -3678,7 +3853,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();
@@ -3888,6 +4063,12 @@ var WikiGraphJobManager = class {
   async clean() {
     return await this.#runtime.run(async () => await 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))
@@ -3963,12 +4144,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 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 WikiGraphArchiveFile6(
             location.archiveFile
@@ -4018,7 +4200,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
                   }),
@@ -4040,9 +4222,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 WikiGraphArchiveFile6(
         location.archiveFile
@@ -4287,12 +4470,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."
     );
@@ -4401,9 +4587,20 @@ import {
   replaceWikiGraphLibraryArchive,
   replaceWikiGraphLibraryMetadata,
   resolveWikiGraphLibrary as resolveWikiGraphLibrary2,
-  scanWikiGraphLibrary
+  scanWikiGraphLibrary,
+  withWikiGraphLibraryLock
 } from "wiki-graph-core";
 import { mkdir as mkdir2 } from "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) {
@@ -4473,6 +4670,43 @@ var WikiGraphLibraryManager = class {
       )
     );
   }
+  async readArchive(target, consume, options = {}) {
+    return await this.#runtime.run(async () => {
+      const parsedTarget = requireLibraryArchiveTarget(target);
+      const library = await resolveWikiGraphLibrary2(parsedTarget);
+      return await withWikiGraphLibraryLock(
+        library.id,
+        "read",
+        async () => {
+          throwIfAborted(options.signal);
+          const archive = await 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(
@@ -4562,7 +4796,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 findWikiGraphLibraryObjects2(
         requireLibraryTarget(target),
         query,
@@ -4575,7 +4811,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 findWikiGraphLibraryArchiveMembers2(
         requireLibraryTarget(target),
         query,
@@ -4616,22 +4854,36 @@ var WikiGraphLibraryManager = class {
     );
   }
   async related(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await listRelatedWikiGraphLibraryObjects2(
+    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 listRelatedWikiGraphLibraryObjects2(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async evidence(target, objectUri, options = {}) {
-    return await this.#runtime.run(
-      async () => await listWikiGraphLibraryEvidence2(
+    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 listWikiGraphLibraryEvidence2(
         requireLibraryTarget(target),
         objectUri,
-        options
-      )
-    );
+        {
+          ...options,
+          ...embeddingProvider === void 0 ? {} : { embeddingProvider }
+        }
+      );
+    });
   }
   async pack(target, objectUri, budget = 5e3) {
     return await this.#runtime.run(
@@ -4713,6 +4965,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
 import {
@@ -4786,11 +5129,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);
@@ -4802,7 +5148,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 ??= ensureWikiGraphHomeSchemaCurrent().catch(
@@ -4815,18 +5161,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.");
 }
@@ -4844,8 +5193,12 @@ import {
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri as formatLocatedChapterUri3,
   formatLocatedWikiGraphUri as formatLocatedWikiGraphUri3,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri as formatWikiGraphLibraryUri3,
+  isWikiGraphJobUri,
+  isWikiGraphUri,
   isSourceLocatorScopeUri as isSourceLocatorScopeUri2,
   isWikiGraphLibraryUri,
   parseChapterPath,
@@ -4853,8 +5206,12 @@ import {
   parseChapterUriPath,
   parseLocatedWikiGraphUri as parseLocatedWikiGraphUri3,
   parseSourceTextJsonl,
+  parseSourceLocatorFragment,
   parseWikiGraphLibraryUri as parseWikiGraphLibraryUri4,
-  parseWikiGraphUriSyntax
+  parseWikiGraphUriSyntax,
+  requireArchiveUri,
+  requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri
 } from "wiki-graph-core";
 export {
   DANGEROUS_RUNTIME_ENV_NAMES,
@@ -4887,6 +5244,7 @@ export {
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
   createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
   createStageLLM,
   createWikiGraphSDK,
@@ -4901,15 +5259,20 @@ export {
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri3 as formatLocatedChapterUri,
   formatLocatedWikiGraphUri3 as formatLocatedWikiGraphUri,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri3 as formatWikiGraphLibraryUri,
   getNodeResourcePath,
+  getWikiGraphSDKProviders,
   getWikiGraphSDKRuntimeContext,
   getWikiGraphSDKStateDir,
   inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri2 as isSourceLocatorScopeUri,
+  isWikiGraphJobUri,
   isWikiGraphLibraryUri,
+  isWikiGraphUri,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,
@@ -4921,6 +5284,7 @@ export {
   parseChapterUriPath,
   parseLocalConfigSection,
   parseLocatedWikiGraphUri3 as parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri4 as parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -4929,10 +5293,14 @@ export {
   readLocalConfigSection,
   readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection,
+  requireArchiveUri,
   requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri,
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,
+  resolveWikiGraphLLMJSON,
   resolveWikispineConfig,
   runWikiGraphQueueWorker,
   validateLocalConfigSection,