wiki-graph-sdk 0.8.1 → 0.8.2

package/dist/index.d.ts

@@ -7,25 +7,26 @@ export { LOCAL_CONFIG_SECTIONS, clearLocalConfigSection, deleteLocalConfigValue,
 import { W as WikiGraphJobRuntime, a as WikiGraphJobManager } from './jobs-CRK-DZ40.js';
 export { b as WikiGraphJob, c as WikiGraphJobBackend, d as WikiGraphJobChapterReference, e as WikiGraphJobCreateOptions, f as WikiGraphJobEnqueueOptions, g as WikiGraphJobEnqueuePlan, h as WikiGraphJobEnqueueResult, i as WikiGraphJobEventListener, j as WikiGraphJobEventsOptions, k as WikiGraphJobListOptions, l as WikiGraphJobSnapshot, m as WikiGraphJobSubscriptionOptions } from './jobs-CRK-DZ40.js';
 import { ContinuationCursor, QueryIndexScope, SearchIndexQueryMode, ArchiveSourceLocatorResult, ArchiveCollectionResult, ArchiveFindResult, ArchiveEvidence, ArchiveRelatedResult, WikiGraphLibraryRecord, WikiGraphLibraryArchiveRecord, ParsedWikiGraphLibraryUri, listWikiGraphLibraryEvidence, WikiGraphLibraryIndexState, rebuildWikiGraphLibraryIndex, ArchiveFindOptions, ArchiveCollectionOptions, readWikiGraphLibraryPage, ArchivePage, listRelatedWikiGraphLibraryObjects, ArchivePack } from 'wiki-graph-core';
-export { ArchiveBacklinkBucket, ArchiveBacklinks, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveEvidence, ArchiveEvidenceItem, ArchiveFindEvidencePreview, ArchiveFindHit, ArchiveFindOptions, ArchiveFindResult, ArchiveListItem, ArchivePack, ArchivePage, ArchiveRelatedResult, ArchiveSourceLocator, ArchiveSourceLocatorResult, ArchiveTriplePattern, BookMeta, BuildJobEvent, BuildJobProgressCounter, BuildJobTarget, ChapterDetails, ChapterEntry, ChapterStage, ChapterTree, ChapterTreeApplyResult, ContinuationCursor, DEFAULT_EXTRACTION_PROMPT, DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT, IndexArtifactKind, LLMPaymentRequiredError, LocatedWikiGraphUri, ParsedWikiGraphLibraryUri, QueryIndexScope, SearchIndexEmbeddingProvider, SourceArtifactInput, WIKI_GRAPH_URI_PREFIX, WikiGraphError, WikiGraphLLMOptions, WikiGraphLibraryIndexState, WikiGraphMaintenanceUpgradeResult, WikiGraphProgressCallback, WikiGraphProgressEvent, WikispineProvider, formatError, formatLocatedChapterResourceUri, formatLocatedChapterSourceCollectionUri, formatLocatedChapterUri, formatLocatedWikiGraphUri, formatWikiGraphCommandUri, formatWikiGraphLibraryUri, isSourceLocatorScopeUri, isWikiGraphLibraryUri, parseChapterPath, parseChapterTreeInput, parseChapterUriPath, parseLocatedWikiGraphUri, parseSourceTextJsonl, parseWikiGraphLibraryUri, parseWikiGraphUriSyntax, resolveExtractionPrompt, resolveKnowledgeGraphRecallPrompt } from 'wiki-graph-core';
+export { ArchiveBacklinkBucket, ArchiveBacklinks, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveEvidence, ArchiveEvidenceItem, ArchiveFindEvidencePreview, ArchiveFindHit, ArchiveFindOptions, ArchiveFindResult, ArchiveListItem, ArchivePack, ArchivePage, ArchiveRelatedResult, ArchiveSourceLocator, ArchiveSourceLocatorResult, ArchiveTriplePattern, BookMeta, BuildJobEvent, BuildJobProgressCounter, BuildJobTarget, ChapterDetails, ChapterEntry, ChapterStage, ChapterTree, ChapterTreeApplyResult, ContinuationCursor, DEFAULT_EXTRACTION_PROMPT, DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT, Directory, File, FileReader, FileWriter, IndexArtifactKind, LLMPaymentRequiredError, LocatedWikiGraphUri, ParsedSourceLocatorFragment, ParsedWikiGraphLibraryUri, ParsedWikiGraphUri, QueryIndexScope, ReadonlyFile, SearchIndexEmbeddingProvider, SearchIndexQueryMode, SourceArtifactInput, WIKI_GRAPH_URI_PREFIX, WikiGraphError, WikiGraphLLMOptions, WikiGraphLibraryIndexState, WikiGraphMaintenanceUpgradeResult, WikiGraphPlatform, WikiGraphProgressCallback, WikiGraphProgressEvent, WikiGraphStorage, WikispineProvider, formatError, formatLocatedChapterResourceUri, formatLocatedChapterSourceCollectionUri, formatLocatedChapterUri, formatLocatedWikiGraphUri, formatSourceArtifactUri, formatSourceLocatorFragment, formatWikiGraphCommandUri, formatWikiGraphLibraryUri, isSourceLocatorScopeUri, isWikiGraphJobUri, isWikiGraphLibraryUri, isWikiGraphUri, parseChapterPath, parseChapterTreeInput, parseChapterUriPath, parseLocatedWikiGraphUri, parseSourceLocatorFragment, parseSourceTextJsonl, parseWikiGraphLibraryUri, parseWikiGraphUriSyntax, requireArchiveUri, requireLocatedObjectOrArchiveUri, requireLocatedObjectUri, resolveExtractionPrompt, resolveKnowledgeGraphRecallPrompt } from 'wiki-graph-core';
 import { WikiGraphConversionManager } from './conversions.js';
 export { WikiGraphConversionFormat, WikiGraphConversionInput, WikiGraphConversionOptions, WikiGraphConversionResult, WikiGraphSourceFormat } from './conversions.js';
 export { WikiGraphQueueWorkerOptions, requireKnowledgeGraphWikispineConfig, runWikiGraphQueueWorker } from './default-worker.js';
 export { DANGEROUS_RUNTIME_ENV_NAMES, WikiGraphEntryEnvPolicy, WikiGraphEntryRuntimeContext, WikiGraphEntryRuntimeOptions, createEntryRuntimeContext } from './entry-context.js';
 export { QueryEmbeddingResult, WikiGraphEmbeddingConfig, WikiGraphEmbeddingProviderName, buildSearchIndexEmbeddingProvider, embedQueryText, embedQueryTextWithLocalConfig, readWikiGraphEmbeddingConfig } from './embedding.js';
+import { W as WikiGraphSDKHost } from './host-pQiVAKEY.js';
 export { buildWikiGraphLLMOptions } from './llm.js';
 import { WikiGraphMaintenanceManager } from './maintenance.js';
 export { WikiGraphLegacyMigrationResult, WikiGraphMaintenanceTarget } from './maintenance.js';
-export { NodeDirectory, NodeFile, createNodeTemplateEnvironment, createNodeWikiGraphStorage, ensureNodeWikiGraphPlatform, getNodeResourcePath, installNodeWikiGraphPlatform, nodeWikiGraphPlatform, withNodeWikiGraphStorage, writeNodeFileHandle } from './node-platform.js';
+export { NodeDirectory, NodeFile, NodeWikiGraphPlatformOptions, NodeWikiGraphStorageOptions, createNodeTemplateEnvironment, createNodeWikiGraphPlatform, createNodeWikiGraphStorage, ensureNodeWikiGraphPlatform, getNodeResourcePath, installNodeWikiGraphPlatform, nodeWikiGraphPlatform, withNodeWikiGraphStorage, writeNodeFileHandle } from './node-platform.js';
 export { DEFAULT_GENERATION_JOB_CONCURRENCY, DEFAULT_GENERATION_REQUEST_CONCURRENCY, GenerationConcurrency, GenerationPerformanceHint, GenerationPlanningCost, createGenerationPerformanceHints, formatGenerationPlanningDuration, formatGenerationPlanningModel, planGenerationTask } from './planning.js';
 import { W as WikiGraphSDKProviders } from './stage-BnWI3Rqt.js';
 export { a as WikiGraphEmbeddingProvider, b as WikiGraphLLMMessage, c as WikiGraphLLMProvider, d as WikiGraphLLMProviderEvent, e as WikiGraphLLMProviderOptions, f as createStageLLM, l as loadRequiredStageConfig, r as resolveWikiGraphLLMJSON } from './stage-BnWI3Rqt.js';
 export { HostedProviderScope, WikiGraphLLMConfig, WikiGraphProvider, WikiGraphRuntimeConfig, loadWikiGraphRuntimeConfig, resolveHostedProviderEndpoint, resolveWikispineConfig } from './runtime-config.js';
 export { nodeWikispineCommandRunner } from './wikispine.js';
 import 'zod';
+import 'wiki-graph-core/platform';
 import 'node:fs/promises';
 import 'nunjucks';
-import 'wiki-graph-core/platform';
 
 interface WikiGraphProviderTestResult {
     readonly durationMs: number;
@@ -75,6 +76,7 @@ interface WikiGraphContinuationContext {
     readonly ids?: readonly string[];
     readonly indexScope: QueryIndexScope;
     readonly libraryQuery?: "archive-members" | "objects";
+    readonly match?: "all" | "any";
     readonly order?: "doc-asc" | "doc-desc";
     readonly query?: string;
     readonly queryMode?: SearchIndexQueryMode;
@@ -212,6 +214,7 @@ interface WikiGraphSDKRuntimeContext {
     readonly cwd: string;
     readonly env: NodeJS.ProcessEnv;
     readonly envPolicy: WikiGraphSDKEnvPolicy;
+    readonly host?: WikiGraphSDKHost;
     readonly providers?: WikiGraphSDKProviders;
     readonly stateDir?: string | undefined;
 }
@@ -224,6 +227,7 @@ interface WikiGraphSDKOptions {
     readonly cwd?: string;
     readonly env?: NodeJS.ProcessEnv;
     readonly envPolicy?: WikiGraphSDKEnvPolicy;
+    readonly host?: WikiGraphSDKHost;
     readonly providers?: WikiGraphSDKProviders;
     readonly stateDir?: string;
 }
@@ -244,4 +248,4 @@ declare class WikiGraphSDK implements WikiGraphJobRuntime {
 }
 declare function createWikiGraphSDK(options?: WikiGraphSDKOptions): WikiGraphSDK;
 
-export { LocalConfigObject, LocalConfigSection, WikiGraphArchiveManager, WikiGraphArchiveTarget, WikiGraphConfigManager, type WikiGraphContinuationContext, WikiGraphContinuationManager, type WikiGraphContinuationOptions, type WikiGraphContinuationPage, WikiGraphConversionManager, WikiGraphJobManager, WikiGraphJobRuntime, WikiGraphLibrary, type WikiGraphLibraryAddArchiveOptions, type WikiGraphLibraryArchiveContent, type WikiGraphLibraryArchiveReadOptions, type WikiGraphLibraryArchiveSnapshot, type WikiGraphLibraryEvidenceOptions, WikiGraphLibraryManager, type WikiGraphLibraryMoveArchiveOptions, type WikiGraphLibraryPageOptions, type WikiGraphLibraryRelatedOptions, type WikiGraphLibraryReplaceArchiveOptions, type WikiGraphLibraryScanSnapshot, type WikiGraphLibrarySearchOptions, type WikiGraphLibrarySnapshot, type WikiGraphLibraryTarget, WikiGraphMaintenanceManager, type WikiGraphProviderTestResult, WikiGraphSDK, type WikiGraphSDKEnvPolicy, type WikiGraphSDKOptions, WikiGraphSDKProviders, type WikiGraphSDKRuntimeContext, createWikiGraphSDK, getWikiGraphSDKProviders, getWikiGraphSDKRuntimeContext, getWikiGraphSDKStateDir, withWikiGraphSDKRuntimeContext };
+export { LocalConfigObject, LocalConfigSection, WikiGraphArchiveManager, WikiGraphArchiveTarget, WikiGraphConfigManager, type WikiGraphContinuationContext, WikiGraphContinuationManager, type WikiGraphContinuationOptions, type WikiGraphContinuationPage, WikiGraphConversionManager, WikiGraphJobManager, WikiGraphJobRuntime, WikiGraphLibrary, type WikiGraphLibraryAddArchiveOptions, type WikiGraphLibraryArchiveContent, type WikiGraphLibraryArchiveReadOptions, type WikiGraphLibraryArchiveSnapshot, type WikiGraphLibraryEvidenceOptions, WikiGraphLibraryManager, type WikiGraphLibraryMoveArchiveOptions, type WikiGraphLibraryPageOptions, type WikiGraphLibraryRelatedOptions, type WikiGraphLibraryReplaceArchiveOptions, type WikiGraphLibraryScanSnapshot, type WikiGraphLibrarySearchOptions, type WikiGraphLibrarySnapshot, type WikiGraphLibraryTarget, WikiGraphMaintenanceManager, type WikiGraphProviderTestResult, WikiGraphSDK, type WikiGraphSDKEnvPolicy, WikiGraphSDKHost, type WikiGraphSDKOptions, WikiGraphSDKProviders, type WikiGraphSDKRuntimeContext, createWikiGraphSDK, getWikiGraphSDKProviders, getWikiGraphSDKRuntimeContext, getWikiGraphSDKStateDir, withWikiGraphSDKRuntimeContext };

package/dist/index.js

@@ -142,6 +142,7 @@ import * as yauzl from "yauzl";
 import * as yazl from "yazl";
 import { Environment, Loader } from "nunjucks";
 import {
+  getWikiGraphPlatform,
   getWikiGraphStorage,
   installWikiGraphPlatform,
   installWikiGraphStorage,
@@ -764,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) {
@@ -809,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) {
@@ -820,7 +829,11 @@ function installNodeWikiGraphPlatform(stateRoot) {
   installWikiGraphStorage(createNodeWikiGraphStorage(stateRoot));
 }
 function ensureNodeWikiGraphPlatform() {
-  installWikiGraphPlatform(nodeWikiGraphPlatform);
+  try {
+    getWikiGraphPlatform();
+  } catch {
+    installWikiGraphPlatform(nodeWikiGraphPlatform);
+  }
   try {
     getWikiGraphStorage();
   } catch {
@@ -2309,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),
@@ -3255,6 +3275,8 @@ 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 },
@@ -3358,6 +3380,8 @@ 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 },
@@ -3584,16 +3608,48 @@ 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)
   );
 }
@@ -5073,11 +5129,13 @@ 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 }
     };
@@ -5103,8 +5161,11 @@ 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
     );
     throwIfAborted2(signal);
@@ -5132,8 +5193,12 @@ import {
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri as formatLocatedChapterUri3,
   formatLocatedWikiGraphUri as formatLocatedWikiGraphUri3,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri as formatWikiGraphLibraryUri3,
+  isWikiGraphJobUri,
+  isWikiGraphUri,
   isSourceLocatorScopeUri as isSourceLocatorScopeUri2,
   isWikiGraphLibraryUri,
   parseChapterPath,
@@ -5141,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,
@@ -5175,6 +5244,7 @@ export {
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
   createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
   createStageLLM,
   createWikiGraphSDK,
@@ -5189,6 +5259,8 @@ export {
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri3 as formatLocatedChapterUri,
   formatLocatedWikiGraphUri3 as formatLocatedWikiGraphUri,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri3 as formatWikiGraphLibraryUri,
   getNodeResourcePath,
@@ -5198,7 +5270,9 @@ export {
   inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri2 as isSourceLocatorScopeUri,
+  isWikiGraphJobUri,
   isWikiGraphLibraryUri,
+  isWikiGraphUri,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,
@@ -5210,6 +5284,7 @@ export {
   parseChapterUriPath,
   parseLocalConfigSection,
   parseLocatedWikiGraphUri3 as parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri4 as parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -5218,7 +5293,10 @@ export {
   readLocalConfigSection,
   readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection,
+  requireArchiveUri,
   requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri,
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,