wiki-graph-sdk 0.7.1 → 0.8.1

package/dist/index.d.ts

@@ -1,23 +1,26 @@
 import { WikiGraphArchiveManager } from './archives.js';
-export { WikiGraphArchiveCover, WikiGraphArchiveCreateOptions, WikiGraphArchiveCreateResult, WikiGraphArchiveEvidenceOptions, WikiGraphArchiveExistsError, WikiGraphArchiveHandle, WikiGraphArchiveIndexStatus, WikiGraphArchiveIndexSyncOptions, WikiGraphArchiveInspectChapterReference, WikiGraphArchiveInspectCoverage, WikiGraphArchiveInspectImprovement, WikiGraphArchiveInspectReport, WikiGraphArchiveListOptions, WikiGraphArchiveLocation, WikiGraphArchivePageOptions, WikiGraphArchiveRelatedOptions, WikiGraphArchiveScope, WikiGraphArchiveScopeOptions, WikiGraphArchiveSearchOptions, WikiGraphArchiveWriteOptions, WikiGraphChapterArtifactStatus, WikiGraphChapterMoveOptions, WikiGraphChapterResetStage, WikiGraphChapterSourceOptions, WikiGraphChapterTreeInput, WikiGraphOperationOptions, createWikiGraphArchiveInspectReport, resolveWikiGraphArchiveLocation } from './archives.js';
+export { WikiGraphArchiveChapterInspection, WikiGraphArchiveCover, WikiGraphArchiveCreateOptions, WikiGraphArchiveCreateResult, WikiGraphArchiveEvidenceOptions, WikiGraphArchiveExistsError, WikiGraphArchiveHandle, WikiGraphArchiveIndexArtifactInspection, WikiGraphArchiveIndexStatus, WikiGraphArchiveIndexSyncOptions, WikiGraphArchiveInspection, WikiGraphArchiveListOptions, WikiGraphArchivePageOptions, WikiGraphArchiveRelatedOptions, WikiGraphArchiveScope, WikiGraphArchiveScopeOptions, WikiGraphArchiveSearchOptions, WikiGraphArchiveWriteOptions, WikiGraphChapterArtifactStatus, WikiGraphChapterMoveOptions, WikiGraphChapterResetStage, WikiGraphChapterSourceOptions, WikiGraphChapterTreeInput, WikiGraphOperationOptions, inspectWikiGraphArchive } from './archives.js';
+import { W as WikiGraphArchiveTarget } from './target-CZ7elwmj.js';
+export { a as WikiGraphArchiveOwnershipError } from './target-CZ7elwmj.js';
 import { LocalConfigSection, LocalConfigObject } from './local-config.js';
 export { LOCAL_CONFIG_SECTIONS, clearLocalConfigSection, deleteLocalConfigValue, maskLocalConfigSection, normalizeLocalConfigKey, parseLocalConfigSection, putLocalConfigValue, readLocalConfigSection, replaceLocalConfigSection, validateLocalConfigSection } from './local-config.js';
-import { W as WikiGraphJobRuntime, a as WikiGraphJobManager } from './jobs-Dd5PMSId.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 WikiGraphJobSubscriptionOptions } from './jobs-Dd5PMSId.js';
-import { ContinuationCursor, QueryIndexScope, ArchiveSourceLocatorResult, ArchiveCollectionResult, ArchiveFindResult, ArchiveEvidence, ArchiveRelatedResult, WikiGraphLibraryRecord, WikiGraphLibraryArchiveRecord, WikiGraphLibraryScanResult, ParsedWikiGraphLibraryUri, WikiGraphLibraryIndexState, rebuildWikiGraphLibraryIndex, ArchiveFindOptions, ArchiveCollectionOptions, readWikiGraphLibraryPage, ArchivePage, listRelatedWikiGraphLibraryObjects, listWikiGraphLibraryEvidence, ArchivePack } from 'wiki-graph-core';
-export { ArchiveBacklinkBucket, ArchiveBacklinks, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveEvidence, ArchiveEvidenceItem, ArchiveFindEvidencePreview, ArchiveFindHit, ArchiveFindOptions, ArchiveFindResult, ArchiveListItem, ArchivePack, ArchivePage, ArchiveRelatedResult, ArchiveSourceLocator, ArchiveSourceLocatorResult, ArchiveTriplePattern, BookMeta, BuildJob, BuildJobEvent, BuildJobProgressCounter, BuildJobTarget, ChapterDetails, ChapterEntry, ChapterStage, ChapterTree, ChapterTreeApplyResult, ContinuationCursor, DEFAULT_EXTRACTION_PROMPT, DEFAULT_KNOWLEDGE_GRAPH_RECALL_PROMPT, File, IndexArtifactKind, LLMPaymentRequiredError, LocatedWikiGraphUri, ParsedWikiGraphLibraryUri, QueryIndexScope, SearchIndexEmbeddingProvider, SourceArtifactInput, WIKI_GRAPH_URI_PREFIX, WikiGraphError, WikiGraphLLMOptions, WikiGraphLibraryArchiveRecord, WikiGraphLibraryIndexState, WikiGraphLibraryRecord, WikiGraphLibraryScanResult, 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';
+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';
 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, WikiGraphEmbeddingProvider, buildSearchIndexEmbeddingProvider, embedQueryText, embedQueryTextWithLocalConfig, readWikiGraphEmbeddingConfig } from './embedding.js';
+export { QueryEmbeddingResult, WikiGraphEmbeddingConfig, WikiGraphEmbeddingProviderName, buildSearchIndexEmbeddingProvider, embedQueryText, embedQueryTextWithLocalConfig, readWikiGraphEmbeddingConfig } from './embedding.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 { DEFAULT_GENERATION_JOB_CONCURRENCY, DEFAULT_GENERATION_REQUEST_CONCURRENCY, GenerationConcurrency, GenerationPerformanceHint, GenerationPlanningCost, createGenerationPerformanceHints, formatGenerationPlanningDuration, formatGenerationPlanningModel, planGenerationTask } from './planning.js';
-export { HostedProviderScope, WikiGraphProvider, WikiGraphRuntimeConfig, loadWikiGraphRuntimeConfig, resolveHostedProviderEndpoint, resolveWikispineConfig } from './runtime-config.js';
-export { createStageLLM, loadRequiredStageConfig } from './stage.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 'node:fs/promises';
@@ -55,7 +58,7 @@ declare class WikiGraphConfigManager {
 
 interface WikiGraphContinuationOptions {
     /** Optional archive locator used to verify that the cursor belongs to it. */
-    readonly archive?: string;
+    readonly archive?: WikiGraphArchiveTarget;
     readonly cursor: string;
     readonly format?: ContinuationCursor["format"];
     readonly limit?: number;
@@ -74,6 +77,7 @@ interface WikiGraphContinuationContext {
     readonly libraryQuery?: "archive-members" | "objects";
     readonly order?: "doc-asc" | "doc-desc";
     readonly query?: string;
+    readonly queryMode?: SearchIndexQueryMode;
     readonly role?: "any" | "object" | "self" | "subject" | undefined;
     readonly skipUnindexed?: boolean;
     readonly sourceContext?: number;
@@ -125,7 +129,11 @@ declare class WikiGraphContinuationManager {
 
 type WikiGraphLibraryTarget = ParsedWikiGraphLibraryUri | string;
 type WikiGraphLibrarySearchOptions = Omit<ArchiveFindOptions, "embeddingProvider">;
-type WikiGraphLibraryPageOptions = Omit<Parameters<typeof readWikiGraphLibraryPage>[2], "wikimediaResolver">;
+type WikiGraphLibraryRelatedOptions = Omit<NonNullable<Parameters<typeof listRelatedWikiGraphLibraryObjects>[2]>, "embeddingProvider">;
+type WikiGraphLibraryEvidenceOptions = Omit<NonNullable<Parameters<typeof listWikiGraphLibraryEvidence>[2]>, "embeddingProvider">;
+type WikiGraphLibraryPageOptions = Omit<Parameters<typeof readWikiGraphLibraryPage>[2], "wikimediaResolver"> & {
+    readonly signal?: AbortSignal;
+};
 interface WikiGraphLibraryAddArchiveOptions {
     readonly inputPath: string;
     readonly target: WikiGraphLibraryTarget;
@@ -135,19 +143,42 @@ interface WikiGraphLibraryMoveArchiveOptions {
     readonly target: WikiGraphLibraryTarget;
     readonly to: string;
 }
+interface WikiGraphLibraryReplaceArchiveOptions {
+    readonly inputPath: string;
+    readonly target: WikiGraphLibraryTarget;
+}
+interface WikiGraphLibraryArchiveContent {
+    readonly mediaType: "application/vnd.wiki-graph.archive";
+    readonly size: number;
+    readonly stream: AsyncIterable<Uint8Array>;
+    readonly uri: string;
+}
+interface WikiGraphLibraryArchiveReadOptions {
+    readonly signal?: AbortSignal;
+}
+interface WikiGraphLibrarySnapshot extends Omit<WikiGraphLibraryRecord, "folder" | "staging"> {
+    readonly folderPath: string;
+}
+type WikiGraphLibraryArchiveSnapshot = Omit<WikiGraphLibraryArchiveRecord, "file">;
+interface WikiGraphLibraryScanSnapshot {
+    readonly archives: readonly WikiGraphLibraryArchiveSnapshot[];
+    readonly library?: WikiGraphLibrarySnapshot;
+}
 declare class WikiGraphLibraryManager {
     #private;
     constructor(runtime: WikiGraphJobRuntime);
     create(folder: string): Promise<WikiGraphLibrary>;
     get(uri?: string): Promise<WikiGraphLibrary>;
-    addArchive(options: WikiGraphLibraryAddArchiveOptions): Promise<WikiGraphLibraryArchiveRecord>;
+    addArchive(options: WikiGraphLibraryAddArchiveOptions): Promise<WikiGraphLibraryArchiveSnapshot>;
     assertCurrent(target: WikiGraphLibraryTarget): Promise<void>;
-    rebind(target: WikiGraphLibraryTarget, folder: string): Promise<WikiGraphLibraryScanResult>;
-    remove(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryRecord>;
-    scan(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryScanResult>;
-    getArchive(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryArchiveRecord>;
-    moveArchive(options: WikiGraphLibraryMoveArchiveOptions): Promise<WikiGraphLibraryArchiveRecord>;
-    removeArchive(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryArchiveRecord>;
+    rebind(target: WikiGraphLibraryTarget, folder: string): Promise<WikiGraphLibraryScanSnapshot>;
+    remove(target: WikiGraphLibraryTarget): Promise<WikiGraphLibrarySnapshot>;
+    scan(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryScanSnapshot>;
+    getArchive(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryArchiveSnapshot>;
+    readArchive<T>(target: WikiGraphLibraryTarget, consume: (content: WikiGraphLibraryArchiveContent) => Promise<T> | T, options?: WikiGraphLibraryArchiveReadOptions): Promise<T>;
+    moveArchive(options: WikiGraphLibraryMoveArchiveOptions): Promise<WikiGraphLibraryArchiveSnapshot>;
+    removeArchive(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryArchiveSnapshot>;
+    replaceArchive(options: WikiGraphLibraryReplaceArchiveOptions): Promise<WikiGraphLibraryArchiveSnapshot>;
     indexState(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryIndexState>;
     rebuildIndex(target: WikiGraphLibraryTarget, onProgress?: Parameters<typeof rebuildWikiGraphLibraryIndex>[1]): Promise<WikiGraphLibraryIndexState>;
     cleanIndex(target: WikiGraphLibraryTarget): Promise<WikiGraphLibraryIndexState>;
@@ -161,19 +192,19 @@ declare class WikiGraphLibraryManager {
     objects(target: WikiGraphLibraryTarget, options?: ArchiveCollectionOptions): Promise<ArchiveCollectionResult>;
     archiveMembers(target: WikiGraphLibraryTarget, options?: ArchiveCollectionOptions): Promise<ArchiveCollectionResult>;
     page(target: WikiGraphLibraryTarget, objectUri: string, options?: WikiGraphLibraryPageOptions): Promise<ArchivePage>;
-    related(target: WikiGraphLibraryTarget, objectUri: string, options?: Parameters<typeof listRelatedWikiGraphLibraryObjects>[2]): Promise<ArchiveRelatedResult>;
-    evidence(target: WikiGraphLibraryTarget, objectUri: string, options?: Parameters<typeof listWikiGraphLibraryEvidence>[2]): Promise<ArchiveEvidence>;
+    related(target: WikiGraphLibraryTarget, objectUri: string, options?: WikiGraphLibraryRelatedOptions): Promise<ArchiveRelatedResult>;
+    evidence(target: WikiGraphLibraryTarget, objectUri: string, options?: WikiGraphLibraryEvidenceOptions): Promise<ArchiveEvidence>;
     pack(target: WikiGraphLibraryTarget, objectUri: string, budget?: number): Promise<ArchivePack>;
     list(): Promise<readonly WikiGraphLibrary[]>;
 }
 declare class WikiGraphLibrary {
     #private;
     constructor(runtime: WikiGraphJobRuntime, record: WikiGraphLibraryRecord);
-    get snapshot(): WikiGraphLibraryRecord;
+    get snapshot(): WikiGraphLibrarySnapshot;
     get uri(): string;
-    archives(): Promise<readonly WikiGraphLibraryArchiveRecord[]>;
-    scan(): Promise<WikiGraphLibraryScanResult>;
-    remove(): Promise<WikiGraphLibraryRecord>;
+    archives(): Promise<readonly WikiGraphLibraryArchiveSnapshot[]>;
+    scan(): Promise<WikiGraphLibraryScanSnapshot>;
+    remove(): Promise<WikiGraphLibrarySnapshot>;
 }
 
 type WikiGraphSDKEnvPolicy = "development" | "production";
@@ -181,16 +212,19 @@ interface WikiGraphSDKRuntimeContext {
     readonly cwd: string;
     readonly env: NodeJS.ProcessEnv;
     readonly envPolicy: WikiGraphSDKEnvPolicy;
+    readonly providers?: WikiGraphSDKProviders;
     readonly stateDir?: string | undefined;
 }
 declare function withWikiGraphSDKRuntimeContext<T>(context: WikiGraphSDKRuntimeContext, operation: () => Promise<T> | T): Promise<T>;
 declare function getWikiGraphSDKRuntimeContext(): WikiGraphSDKRuntimeContext;
 declare function getWikiGraphSDKStateDir(): string | undefined;
+declare function getWikiGraphSDKProviders(): WikiGraphSDKProviders;
 
 interface WikiGraphSDKOptions {
     readonly cwd?: string;
     readonly env?: NodeJS.ProcessEnv;
     readonly envPolicy?: WikiGraphSDKEnvPolicy;
+    readonly providers?: WikiGraphSDKProviders;
     readonly stateDir?: string;
 }
 declare class WikiGraphSDK implements WikiGraphJobRuntime {
@@ -210,4 +244,4 @@ declare class WikiGraphSDK implements WikiGraphJobRuntime {
 }
 declare function createWikiGraphSDK(options?: WikiGraphSDKOptions): WikiGraphSDK;
 
-export { LocalConfigObject, LocalConfigSection, WikiGraphArchiveManager, WikiGraphConfigManager, type WikiGraphContinuationContext, WikiGraphContinuationManager, type WikiGraphContinuationOptions, type WikiGraphContinuationPage, WikiGraphConversionManager, WikiGraphJobManager, WikiGraphJobRuntime, WikiGraphLibrary, type WikiGraphLibraryAddArchiveOptions, WikiGraphLibraryManager, type WikiGraphLibraryMoveArchiveOptions, type WikiGraphLibraryPageOptions, type WikiGraphLibrarySearchOptions, type WikiGraphLibraryTarget, WikiGraphMaintenanceManager, type WikiGraphProviderTestResult, WikiGraphSDK, type WikiGraphSDKEnvPolicy, type WikiGraphSDKOptions, type WikiGraphSDKRuntimeContext, createWikiGraphSDK, 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, type WikiGraphSDKOptions, WikiGraphSDKProviders, type WikiGraphSDKRuntimeContext, createWikiGraphSDK, getWikiGraphSDKProviders, getWikiGraphSDKRuntimeContext, getWikiGraphSDKStateDir, withWikiGraphSDKRuntimeContext };