wiki-graph-sdk 0.8.0 → 0.8.2

package/dist/archives.d.ts

@@ -1,7 +1,10 @@
-import { ChapterEntry, IndexArtifactKind, ReadonlyDocument, WikiGraphProgressCallback, QueryIndexScope, ArchiveFindOptions, ArchiveFindResult, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveSourceLocatorResult, readSearchIndexCapabilityStatus, rebuildArchiveSearchIndex, ChapterDetails, ChapterStage, setChapterSource, setChapterTitle, ChapterTree, applyChapterTree, ChapterTreeApplyResult, ArchivePage, ArchiveRelatedResult, ArchiveEvidence, ArchivePack, BookMeta } from 'wiki-graph-core';
-import { W as WikiGraphJobRuntime } from './jobs-xIm_kshM.js';
+import { ChapterEntry, IndexArtifactKind, ReadonlyDocument, WikiGraphProgressCallback, SearchIndexQueryMode, QueryIndexScope, ArchiveFindOptions, ArchiveFindResult, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveSourceLocatorResult, readSearchIndexCapabilityStatus, rebuildArchiveSearchIndex, ChapterDetails, ChapterStage, setChapterSource, setChapterTitle, ChapterTree, applyChapterTree, ChapterTreeApplyResult, ArchivePage, ArchiveRelatedResult, ArchiveEvidence, ArchivePack, BookMeta } from 'wiki-graph-core';
+import { W as WikiGraphJobRuntime } from './jobs-CRK-DZ40.js';
 import { W as WikiGraphArchiveTarget } from './target-CZ7elwmj.js';
 export { a as WikiGraphArchiveOwnershipError } from './target-CZ7elwmj.js';
+import './default-worker.js';
+import './runtime-config.js';
+import 'zod';
 
 interface WikiGraphArchiveIndexArtifactInspection {
     readonly current: boolean;
@@ -128,6 +131,7 @@ interface WikiGraphArchiveRelatedOptions extends WikiGraphOperationOptions {
     readonly limit?: number;
     readonly order?: "doc-asc" | "doc-desc";
     readonly query?: string;
+    readonly queryMode?: SearchIndexQueryMode;
     readonly role?: "any" | "object" | "self" | "subject";
     readonly skipUnindexed?: boolean;
     readonly sourceContext?: number;
@@ -137,6 +141,7 @@ interface WikiGraphArchiveEvidenceOptions extends WikiGraphOperationOptions {
     readonly limit?: number;
     readonly order?: "doc-asc" | "doc-desc";
     readonly query?: string;
+    readonly queryMode?: SearchIndexQueryMode;
     readonly skipUnindexed?: boolean;
     readonly sourceContext?: number;
 }
@@ -170,6 +175,8 @@ declare class WikiGraphArchiveHandle {
         readonly rebuilt: boolean;
     }>;
     cleanSearchIndex(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveIndexStatus>;
+    /** Clear cached search sessions without changing the archive index. */
+    clearSearchSessions(options?: WikiGraphOperationOptions): Promise<void>;
     listChapters(options?: WikiGraphOperationOptions): Promise<readonly ChapterEntry[]>;
     getChapter(path: string, options?: WikiGraphOperationOptions): Promise<ChapterEntry>;
     addChapter(options: {
@@ -200,6 +207,7 @@ declare class WikiGraphArchiveHandle {
     getMetadata(objectPath: string, options?: WikiGraphOperationOptions): Promise<Readonly<Record<string, unknown>>>;
     readBookMeta(options?: WikiGraphOperationOptions): Promise<BookMeta | undefined>;
     replaceBookMeta(meta: BookMeta, options?: WikiGraphArchiveWriteOptions): Promise<BookMeta>;
+    setArchiveTitle(title: string | null, options?: WikiGraphArchiveWriteOptions): Promise<string | null>;
     readCover(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveCover | undefined>;
     replaceMetadata(objectPath: string, value: Readonly<Record<string, unknown>>, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;
     putMetadata(objectPath: string, key: string, value: unknown, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;

package/dist/archives.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,
@@ -832,12 +834,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";
@@ -1055,8 +1061,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")
@@ -1252,6 +1258,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";
@@ -1455,12 +1469,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,
@@ -1750,6 +1770,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;
@@ -2001,13 +2023,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 }
@@ -2115,6 +2139,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),
@@ -2305,6 +2336,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, {
@@ -2313,19 +2347,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 }
         });
       },
@@ -2337,6 +2374,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, {
@@ -2345,19 +2385,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 }
         });
       },
@@ -2391,6 +2434,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(
@@ -2461,11 +2522,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(
@@ -2474,6 +2544,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 };