wiki-graph-core 0.3.1

package/dist/facade/app.js

@@ -0,0 +1,141 @@
+import { resolveDataDirPath } from "../common/data-dir.js";
+import { withLoggingContext } from "../common/logging.js";
+import { LLM } from "../llm/index.js";
+import {
+  digestEpubSession,
+  digestMarkdownSession,
+  digestTextStreamSession,
+  digestTxtSession
+} from "./digest.js";
+import { createDefaultWikiGraphSampling } from "./llm-sampling.js";
+import { WikiGraphArchiveFile } from "../wikg/index.js";
+const DATA_DIR_PATH = resolveDataDirPath();
+const DEFAULT_EXTRACTION_PROMPT = "Focus on the main storyline and key character developments. Preserve important dialogues and critical plot points. Background descriptions and minor details can be compressed significantly.";
+class WikiGraph {
+  #debugLogDirPath;
+  #llm;
+  #verbose;
+  constructor(options) {
+    this.#debugLogDirPath = options.debugLogDirPath;
+    this.#verbose = options.verbose ?? false;
+    if (options.llm === void 0) {
+      this.#llm = void 0;
+      return;
+    }
+    const llmOptions = normalizeLLMOptions(options.llm);
+    this.#llm = new LLM({
+      dataDirPath: DATA_DIR_PATH,
+      sampling: createDefaultWikiGraphSampling({
+        ...llmOptions.temperature === void 0 ? {} : { temperature: llmOptions.temperature },
+        ...llmOptions.topP === void 0 ? {} : { topP: llmOptions.topP }
+      }),
+      ...llmOptions
+    });
+  }
+  async digestEpubSession(options, operation) {
+    return await this.#withLogging(
+      "digest-epub",
+      async () => await digestEpubSession(this.#createSourceOptions(options), operation)
+    );
+  }
+  async digestMarkdownSession(options, operation) {
+    return await this.#withLogging(
+      "digest-markdown",
+      async () => await digestMarkdownSession(
+        this.#createSourceOptions(options),
+        operation
+      )
+    );
+  }
+  async digestTextStreamSession(options, operation) {
+    return await this.#withLogging(
+      "digest-text-stream",
+      async () => await digestTextStreamSession(
+        {
+          extractionPrompt: resolveExtractionPrompt(options.extractionPrompt),
+          ...optionalLLM(this.#resolveStageLLM(options.targetStage)),
+          ...options.onProgress === void 0 ? {} : { onProgress: options.onProgress },
+          stream: options.stream,
+          ...this.#debugLogDirPath === void 0 ? {} : { logDirPath: this.#debugLogDirPath },
+          ...options.bookLanguage === void 0 ? {} : { bookLanguage: options.bookLanguage },
+          ...options.documentDirPath === void 0 ? {} : { documentDirPath: options.documentDirPath },
+          ...options.sourceFormat === void 0 ? {} : { sourceFormat: options.sourceFormat },
+          ...options.targetStage === void 0 ? {} : { targetStage: options.targetStage },
+          ...options.title === void 0 ? {} : { title: options.title },
+          ...options.userLanguage === void 0 ? {} : { userLanguage: options.userLanguage }
+        },
+        operation
+      )
+    );
+  }
+  async digestTxtSession(options, operation) {
+    return await this.#withLogging(
+      "digest-txt",
+      async () => await digestTxtSession(this.#createSourceOptions(options), operation)
+    );
+  }
+  async openSession(path, operation, options = {}) {
+    return await this.#withLogging(
+      "open-wikg",
+      async () => await new WikiGraphArchiveFile(path).read(operation, {
+        ...options.documentDirPath === void 0 ? {} : { documentDirPath: options.documentDirPath }
+      })
+    );
+  }
+  #createSourceOptions(options) {
+    return {
+      extractionPrompt: resolveExtractionPrompt(options.extractionPrompt),
+      ...optionalLLM(this.#resolveStageLLM(options.targetStage)),
+      ...options.onProgress === void 0 ? {} : { onProgress: options.onProgress },
+      path: options.path,
+      ...this.#debugLogDirPath === void 0 ? {} : { logDirPath: this.#debugLogDirPath },
+      ...options.documentDirPath === void 0 ? {} : { documentDirPath: options.documentDirPath },
+      ...options.targetStage === void 0 ? {} : { targetStage: options.targetStage },
+      ...options.userLanguage === void 0 ? {} : { userLanguage: options.userLanguage }
+    };
+  }
+  #requireLLM() {
+    if (this.#llm === void 0) {
+      throw new Error(
+        "LLM is required for digest operations. Configure `llm` when constructing WikiGraph."
+      );
+    }
+    return this.#llm;
+  }
+  #resolveStageLLM(targetStage) {
+    if (targetStage === "planned" || targetStage === "sourced") {
+      return void 0;
+    }
+    return this.#requireLLM();
+  }
+  async #withLogging(operation, task) {
+    return await withLoggingContext(
+      {
+        operation,
+        ...this.#debugLogDirPath === void 0 ? {} : { logDirPath: this.#debugLogDirPath },
+        ...this.#verbose ? { verbose: true } : {}
+      },
+      task
+    );
+  }
+}
+function optionalLLM(llm) {
+  return llm === void 0 ? {} : { llm };
+}
+function normalizeLLMOptions(llm) {
+  if (isWikiGraphLLMOptions(llm)) {
+    return llm;
+  }
+  return { model: llm };
+}
+function isWikiGraphLLMOptions(llm) {
+  return typeof llm === "object" && llm !== null && "model" in llm;
+}
+function resolveExtractionPrompt(prompt) {
+  const normalizedPrompt = prompt?.trim();
+  return normalizedPrompt === void 0 || normalizedPrompt === "" ? DEFAULT_EXTRACTION_PROMPT : normalizedPrompt;
+}
+export {
+  WikiGraph
+};
+//# sourceMappingURL=app.js.map

package/dist/facade/app.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/facade/app.ts"],"sourcesContent":["import type { LanguageModel } from \"ai\";\n\nimport { resolveDataDirPath } from \"../common/data-dir.js\";\nimport type { Language } from \"../common/language.js\";\nimport type { WikiGraphScope } from \"../common/llm-scope.js\";\nimport { withLoggingContext } from \"../common/logging.js\";\nimport { LLM } from \"../llm/index.js\";\nimport type {\n  DigestProgressEvent,\n  SerialDiscoveryItem,\n  SerialsDiscoveredEvent,\n  SerialProgressEvent,\n  WikiGraphProgressCallback,\n  WikiGraphProgressEvent,\n  WikiGraphProgressEventType,\n  WikiGraphOperation,\n} from \"../progress/index.js\";\n\nimport {\n  digestEpubSession,\n  digestMarkdownSession,\n  digestTextStreamSession,\n  digestTxtSession,\n  type DigestDocumentSessionOptions,\n  type DigestSourceSessionOptions,\n  type DigestTextStreamSessionOptions,\n} from \"./digest.js\";\nimport { createDefaultWikiGraphSampling } from \"./llm-sampling.js\";\nimport { WikiGraphArchiveFile } from \"../wikg/index.js\";\nimport type { WikiGraphArchive } from \"./wiki-graph-archive.js\";\nimport type { ChapterStage } from \"./chapter.js\";\n\nconst DATA_DIR_PATH = resolveDataDirPath();\n\nconst DEFAULT_EXTRACTION_PROMPT =\n  \"Focus on the main storyline and key character developments. Preserve important dialogues and critical plot points. Background descriptions and minor details can be compressed significantly.\";\n\nexport interface WikiGraphLLMOptions {\n  readonly cacheDirPath?: string;\n  readonly concurrent?: number;\n  readonly logDirPath?: string;\n  readonly model: LanguageModel;\n  readonly retryIntervalSeconds?: number;\n  readonly retryTimes?: number;\n  readonly stream?: boolean;\n  readonly temperature?: number | readonly number[];\n  readonly timeout?: number;\n  readonly topP?: number | readonly number[];\n}\n\nexport interface WikiGraphOptions {\n  readonly debugLogDirPath?: string;\n  readonly llm?: LanguageModel | WikiGraphLLMOptions;\n  readonly verbose?: boolean;\n}\n\nexport type WikiGraphOpenSessionOptions = DigestDocumentSessionOptions;\n\nexport interface WikiGraphSourceSessionOptions extends DigestDocumentSessionOptions {\n  readonly extractionPrompt?: string;\n  readonly onProgress?: WikiGraphProgressCallback;\n  readonly path: string;\n  readonly targetStage?: ChapterStage;\n  readonly userLanguage?: Language;\n}\n\nexport interface WikiGraphTextStreamSessionOptions extends DigestDocumentSessionOptions {\n  readonly bookLanguage?: string | null;\n  readonly extractionPrompt?: string;\n  readonly onProgress?: WikiGraphProgressCallback;\n  readonly sourceFormat?: \"markdown\" | \"txt\";\n  readonly stream: AsyncIterable<string> | Iterable<string>;\n  readonly targetStage?: ChapterStage;\n  readonly title?: string | null;\n  readonly userLanguage?: Language;\n}\n\nexport class WikiGraph {\n  readonly #debugLogDirPath: string | undefined;\n  readonly #llm: LLM<WikiGraphScope> | undefined;\n  readonly #verbose: boolean;\n\n  public constructor(options: WikiGraphOptions) {\n    this.#debugLogDirPath = options.debugLogDirPath;\n    this.#verbose = options.verbose ?? false;\n    if (options.llm === undefined) {\n      this.#llm = undefined;\n      return;\n    }\n    const llmOptions = normalizeLLMOptions(options.llm);\n\n    this.#llm = new LLM<WikiGraphScope>({\n      dataDirPath: DATA_DIR_PATH,\n      sampling: createDefaultWikiGraphSampling({\n        ...(llmOptions.temperature === undefined\n          ? {}\n          : { temperature: llmOptions.temperature }),\n        ...(llmOptions.topP === undefined ? {} : { topP: llmOptions.topP }),\n      }),\n      ...llmOptions,\n    });\n  }\n\n  public async digestEpubSession<T>(\n    options: WikiGraphSourceSessionOptions,\n    operation: (digest: WikiGraphArchive) => Promise<T> | T,\n  ): Promise<T> {\n    return await this.#withLogging(\n      \"digest-epub\",\n      async () =>\n        await digestEpubSession(this.#createSourceOptions(options), operation),\n    );\n  }\n\n  public async digestMarkdownSession<T>(\n    options: WikiGraphSourceSessionOptions,\n    operation: (digest: WikiGraphArchive) => Promise<T> | T,\n  ): Promise<T> {\n    return await this.#withLogging(\n      \"digest-markdown\",\n      async () =>\n        await digestMarkdownSession(\n          this.#createSourceOptions(options),\n          operation,\n        ),\n    );\n  }\n\n  public async digestTextStreamSession<T>(\n    options: WikiGraphTextStreamSessionOptions,\n    operation: (digest: WikiGraphArchive) => Promise<T> | T,\n  ): Promise<T> {\n    return await this.#withLogging(\n      \"digest-text-stream\",\n      async () =>\n        await digestTextStreamSession(\n          {\n            extractionPrompt: resolveExtractionPrompt(options.extractionPrompt),\n            ...optionalLLM(this.#resolveStageLLM(options.targetStage)),\n            ...(options.onProgress === undefined\n              ? {}\n              : { onProgress: options.onProgress }),\n            stream: options.stream,\n            ...(this.#debugLogDirPath === undefined\n              ? {}\n              : { logDirPath: this.#debugLogDirPath }),\n            ...(options.bookLanguage === undefined\n              ? {}\n              : { bookLanguage: options.bookLanguage }),\n            ...(options.documentDirPath === undefined\n              ? {}\n              : { documentDirPath: options.documentDirPath }),\n            ...(options.sourceFormat === undefined\n              ? {}\n              : { sourceFormat: options.sourceFormat }),\n            ...(options.targetStage === undefined\n              ? {}\n              : { targetStage: options.targetStage }),\n            ...(options.title === undefined ? {} : { title: options.title }),\n            ...(options.userLanguage === undefined\n              ? {}\n              : { userLanguage: options.userLanguage }),\n          } satisfies DigestTextStreamSessionOptions,\n          operation,\n        ),\n    );\n  }\n\n  public async digestTxtSession<T>(\n    options: WikiGraphSourceSessionOptions,\n    operation: (digest: WikiGraphArchive) => Promise<T> | T,\n  ): Promise<T> {\n    return await this.#withLogging(\n      \"digest-txt\",\n      async () =>\n        await digestTxtSession(this.#createSourceOptions(options), operation),\n    );\n  }\n\n  public async openSession<T>(\n    path: string,\n    operation: (digest: WikiGraphArchive) => Promise<T> | T,\n    options: WikiGraphOpenSessionOptions = {},\n  ): Promise<T> {\n    return await this.#withLogging(\n      \"open-wikg\",\n      async () =>\n        await new WikiGraphArchiveFile(path).read(operation, {\n          ...(options.documentDirPath === undefined\n            ? {}\n            : { documentDirPath: options.documentDirPath }),\n        }),\n    );\n  }\n\n  #createSourceOptions(\n    options: WikiGraphSourceSessionOptions,\n  ): DigestSourceSessionOptions {\n    return {\n      extractionPrompt: resolveExtractionPrompt(options.extractionPrompt),\n      ...optionalLLM(this.#resolveStageLLM(options.targetStage)),\n      ...(options.onProgress === undefined\n        ? {}\n        : { onProgress: options.onProgress }),\n      path: options.path,\n      ...(this.#debugLogDirPath === undefined\n        ? {}\n        : { logDirPath: this.#debugLogDirPath }),\n      ...(options.documentDirPath === undefined\n        ? {}\n        : { documentDirPath: options.documentDirPath }),\n      ...(options.targetStage === undefined\n        ? {}\n        : { targetStage: options.targetStage }),\n      ...(options.userLanguage === undefined\n        ? {}\n        : { userLanguage: options.userLanguage }),\n    };\n  }\n\n  #requireLLM(): LLM<WikiGraphScope> {\n    if (this.#llm === undefined) {\n      throw new Error(\n        \"LLM is required for digest operations. Configure `llm` when constructing WikiGraph.\",\n      );\n    }\n\n    return this.#llm;\n  }\n\n  #resolveStageLLM(\n    targetStage: ChapterStage | undefined,\n  ): LLM<WikiGraphScope> | undefined {\n    if (targetStage === \"planned\" || targetStage === \"sourced\") {\n      return undefined;\n    }\n\n    return this.#requireLLM();\n  }\n\n  async #withLogging<T>(operation: string, task: () => Promise<T>): Promise<T> {\n    return await withLoggingContext(\n      {\n        operation,\n        ...(this.#debugLogDirPath === undefined\n          ? {}\n          : { logDirPath: this.#debugLogDirPath }),\n        ...(this.#verbose ? { verbose: true } : {}),\n      },\n      task,\n    );\n  }\n}\n\nexport type {\n  DigestProgressEvent,\n  SerialDiscoveryItem,\n  SerialsDiscoveredEvent,\n  SerialProgressEvent,\n  WikiGraphProgressCallback,\n  WikiGraphProgressEvent,\n  WikiGraphProgressEventType,\n  WikiGraphOperation,\n};\n\nfunction optionalLLM(\n  llm: LLM<WikiGraphScope> | undefined,\n): { readonly llm: LLM<WikiGraphScope> } | Record<string, never> {\n  return llm === undefined ? {} : { llm };\n}\n\nfunction normalizeLLMOptions(\n  llm: NonNullable<WikiGraphOptions[\"llm\"]>,\n): WikiGraphLLMOptions {\n  if (isWikiGraphLLMOptions(llm)) {\n    return llm;\n  }\n\n  return { model: llm };\n}\n\nfunction isWikiGraphLLMOptions(\n  llm: NonNullable<WikiGraphOptions[\"llm\"]>,\n): llm is WikiGraphLLMOptions {\n  return typeof llm === \"object\" && llm !== null && \"model\" in llm;\n}\n\nfunction resolveExtractionPrompt(prompt: string | undefined): string {\n  const normalizedPrompt = prompt?.trim();\n\n  return normalizedPrompt === undefined || normalizedPrompt === \"\"\n    ? DEFAULT_EXTRACTION_PROMPT\n    : normalizedPrompt;\n}\n"],"mappings":"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","names":[]}

package/dist/facade/build-queue.d.ts

@@ -0,0 +1,181 @@
+import { GcContext, GcJobResult } from '../gc/types.js';
+
+declare const BUILD_JOB_STATES: readonly ["queued", "running", "canceling", "paused", "succeeded", "failed", "canceled"];
+type BuildJobState = (typeof BUILD_JOB_STATES)[number];
+type BuildJobTarget = "knowledge-graph" | "reading-graph" | "reading-summary";
+type BuildJobProgressPhase = "committing" | "enrichment" | "grounding" | "matching" | "narrowing" | "relation-discovery" | "screening";
+type BuildJobProgressUnit = "candidate" | "char" | "item" | "page" | "qid" | "sentence" | "window" | "record";
+interface BuildJobProgressCounter {
+    readonly done: number;
+    readonly name: string;
+    readonly total: number;
+    readonly unit: BuildJobProgressUnit | "word";
+}
+interface BuildJobTokenUsage {
+    readonly cacheReadTokens?: number;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+interface BuildJob {
+    readonly archiveKey: string;
+    readonly archivePath: string;
+    readonly cachePath: string;
+    readonly chapterId: number;
+    readonly createdAt: number;
+    readonly currentStep?: BuildJobTarget;
+    readonly errorJSON?: string;
+    readonly eventsPath: string;
+    readonly finishedAt?: number;
+    readonly jobId: string;
+    readonly inputRevision?: number;
+    readonly logPath: string;
+    readonly llmJSON?: string;
+    readonly ownerId?: string;
+    readonly ownerPid?: number;
+    readonly prompt?: string;
+    readonly queueRank: number;
+    readonly state: BuildJobState;
+    readonly readingSummaryStartedAt?: number;
+    readonly target: BuildJobTarget;
+    readonly updatedAt: number;
+    readonly workspacePath: string;
+}
+type BuildJobEvent = {
+    readonly at: number;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly state: BuildJobState;
+    readonly type: "created" | "paused" | "resumed" | "boosted" | "canceling";
+} | {
+    readonly at: number;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly from: BuildJobTarget;
+    readonly to: BuildJobTarget;
+    readonly type: "target_changed";
+} | {
+    readonly at: number;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly state: "running";
+    readonly type: "started";
+} | {
+    readonly at: number;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly state: "queued";
+    readonly type: "requeued";
+} | {
+    readonly at: number;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly step: BuildJobTarget;
+    readonly type: "step_started" | "step_completed";
+} | {
+    readonly at: number;
+    readonly counters: readonly BuildJobProgressCounter[];
+    readonly jobId: string;
+    readonly phase?: BuildJobProgressPhase;
+    readonly seq: number;
+    readonly step?: BuildJobTarget;
+    readonly tokens?: BuildJobTokenUsage;
+    readonly type: "status_snapshot";
+} | {
+    readonly at: number;
+    readonly error?: unknown;
+    readonly jobId: string;
+    readonly seq: number;
+    readonly state: "failed" | "canceled" | "succeeded";
+    readonly type: "failed" | "canceled" | "succeeded";
+};
+interface AddBuildJobOptions {
+    readonly archivePath: string;
+    readonly boost?: boolean;
+    readonly chapterId: number;
+    readonly jobId?: string;
+    readonly llmJSON?: string;
+    readonly prompt?: string;
+    readonly target: BuildJobTarget;
+}
+interface BuildJobListOptions {
+    readonly activeOnly?: boolean;
+    readonly all?: boolean;
+    readonly archivePath?: string;
+}
+interface BuildJobWorkerOptions {
+    readonly concurrency: number;
+    readonly executeJob: (job: BuildJob, reporter: BuildJobProgressReporter, context: BuildJobExecutionContext) => Promise<void>;
+    readonly idleTimeoutMs?: number;
+}
+interface BuildJobExecutionContext {
+    readonly signal: AbortSignal;
+}
+interface BuildJobProgressReporter {
+    addOutputCharacters(characters: number): Promise<void>;
+    addTokenUsage(usage: BuildJobTokenUsage): Promise<void>;
+    setTotals(input: {
+        readonly totalGraphWords?: number;
+        readonly totalReadingSummaryWords?: number;
+    }): Promise<void>;
+    stepCompleted(step: BuildJobTarget): Promise<void>;
+    stepStarted(step: BuildJobTarget): Promise<void>;
+    updateWords(input: {
+        readonly graphWords?: number;
+        readonly readingSummaryWords?: number;
+    }): Promise<void>;
+    updatePhase(input: {
+        readonly done: number;
+        readonly force?: boolean;
+        readonly phase: BuildJobProgressPhase;
+        readonly phaseDetail?: string;
+        readonly total: number;
+        readonly unit: BuildJobProgressUnit;
+    }): Promise<void>;
+    throwIfStopped(): Promise<void>;
+}
+type BuildJobConflictScope = {
+    readonly kind: "archive";
+} | {
+    readonly chapterIds: readonly number[];
+    readonly kind: "chapter";
+};
+declare function addBuildJob(options: AddBuildJobOptions): Promise<BuildJob>;
+declare function recordBuildJobInputRevision(input: {
+    readonly currentRevision: number;
+    readonly jobId: string;
+    readonly ownerId: string;
+}): Promise<BuildJob>;
+declare function assertBuildJobInputRevision(input: {
+    readonly currentRevision: number;
+    readonly jobId: string;
+    readonly ownerId: string;
+}): Promise<void>;
+declare function listBuildJobs(options?: BuildJobListOptions): Promise<BuildJob[]>;
+declare function getBuildJob(jobId: string): Promise<BuildJob>;
+declare function resolveBuildJobId(jobIdPrefix: string): Promise<string>;
+declare function pauseBuildJob(jobId: string): Promise<BuildJob>;
+declare function resumeBuildJob(jobId: string): Promise<BuildJob>;
+declare function cancelBuildJob(jobId: string): Promise<BuildJob>;
+declare function boostBuildJob(jobId: string): Promise<BuildJob>;
+declare function updateBuildJobTarget(jobId: string, target: BuildJobTarget): Promise<BuildJob>;
+declare function assertNoActiveBuildJobs(input: {
+    readonly archivePath: string;
+    readonly chapterIds: readonly number[];
+    readonly operation: string;
+    readonly requiresTarget?: BuildJobTarget;
+}): Promise<void>;
+declare function assertNoActiveBuildJobConflicts(input: {
+    readonly archivePath: string;
+    readonly operation: string;
+    readonly requiresTarget?: BuildJobTarget;
+    readonly scope: BuildJobConflictScope;
+}): Promise<void>;
+declare function runBuildJobWorker(options: BuildJobWorkerOptions): Promise<void>;
+declare function readBuildJobEvents(job: Pick<BuildJob, "eventsPath">): Promise<BuildJobEvent[]>;
+declare function cleanBuildJobs(options?: {
+    readonly olderThanMs?: number;
+    readonly states?: readonly BuildJobState[];
+}): Promise<number>;
+declare function runBuildQueueGc(context: GcContext): Promise<GcJobResult>;
+
+export { type AddBuildJobOptions, BUILD_JOB_STATES, type BuildJob, type BuildJobConflictScope, type BuildJobEvent, type BuildJobExecutionContext, type BuildJobListOptions, type BuildJobProgressCounter, type BuildJobProgressPhase, type BuildJobProgressReporter, type BuildJobProgressUnit, type BuildJobState, type BuildJobTarget, type BuildJobTokenUsage, type BuildJobWorkerOptions, addBuildJob, assertBuildJobInputRevision, assertNoActiveBuildJobConflicts, assertNoActiveBuildJobs, boostBuildJob, cancelBuildJob, cleanBuildJobs, getBuildJob, listBuildJobs, pauseBuildJob, readBuildJobEvents, recordBuildJobInputRevision, resolveBuildJobId, resumeBuildJob, runBuildJobWorker, runBuildQueueGc, updateBuildJobTarget };