wiki-graph-core 0.3.1 → 0.4.1

package/data/help/topics/runtime.jinja

@@ -25,7 +25,7 @@ Generation job behavior:
   - Reading Graph, Reading Summary, and Knowledge Graph generation run as device-local jobs.
   - Generation jobs consume LLM tokens, may incur provider charges, and can run for minutes to hours on large archives.
   - `wikg://local/job add` requires `--accept-cost` as an explicit cost/time acknowledgement.
-  - Job records live under `~/.{{ commandName }}/jobs`.
+  - Job records live under `~/.wikigraph/jobs`.
   - `wikg://local/job add`, `wikg://local/job/<job-id> resume`, `wikg://local/job/<job-id> boost`, and `wikg://local/job/<job-id>/target set` try to start a transient worker.
   - The worker exits after idle time; it is not intended to be a permanent daemon.
   - `wikg://local/job/<job-id> watch --jsonl` is the stable agent-facing progress stream.
@@ -41,15 +41,30 @@ Progress and diagnostics:
 Workspace behavior:
   - Archive creation and EPUB import use temporary workspaces.
   - `transform --digest-dir <path>` uses the provided digest workspace for source digest runs.
-  - Generation jobs use per-job directories under `~/.{{ commandName }}/jobs/work`, `~/.{{ commandName }}/jobs/cache`, and `~/.{{ commandName }}/jobs/logs`.
+  - Generation jobs use per-job directories under `~/.wikigraph/jobs/work`, `~/.wikigraph/jobs/cache`, and `~/.wikigraph/jobs/logs`.
   - Succeeded jobs delete their workspace by default.
   - Failed and canceled jobs keep their workspace for debugging until cleanup.
   - Job events, logs, and LLM cache are kept until the job record is cleaned.
 
+Local state map:
+  - `~/.wikigraph/core.sqlite`: home registry and shared local state.
+  - `~/.wikigraph/cache/search-sessions.sqlite`: search query cache sessions used by paged search results.
+  - `~/.wikigraph/cache/continuation-cursors.sqlite`: opaque `wg next` continuation cursor records.
+  - `~/.wikigraph/cache/cache.sqlite`: Wikipedia page and other reusable local cache records.
+  - `~/.wikigraph/jobs`: durable generation job records, events, workspaces, caches, and logs.
+  - `~/.wikigraph/jobs/work`: per-job workspaces; failed and canceled jobs keep these for debugging.
+  - `~/.wikigraph/jobs/cache`: per-job LLM/cache artifacts kept with job records until cleanup.
+  - `~/.wikigraph/jobs/logs`: per-job diagnostic logs.
+  - `~/.wikigraph/staging`: archive coordinator state, materialized archive entries, local archive index staging, and library aggregate indexes.
+  - Search query caches and continuation cursors are local derived state; use `{{ commandName }} next --help` for cursor continuation and `{{ commandName }} gc --help` for cleanup.
+  - Do not manually delete active job, staging, or cursor state while commands are running; prefer `{{ commandName }} gc` and command-specific cleanup paths.
+
 In-place archive edits:
   - Mutating `.wikg` commands go through the archive coordinator.
   - Active generation jobs block destructive chapter maintenance edits for the same chapter.
-  - Archive writes are coordinated through `~/.{{ commandName }}/staging`.
+  - Archive writes are coordinated through `~/.wikigraph/staging`.
+  - Library aggregate indexes are local derived state under staging and can be removed by cleanup when orphaned.
+  - Library cursors store the library index scope and re-check index freshness before continuing.
 
 Where to go next:
   - Need the normal workflow before debugging:
@@ -60,3 +75,5 @@ Where to go next:
     {{ commandName }} help format
   - Need URI command routing:
     {{ commandName }} help uri
+  - Need library registry, membership, path binding, or index behavior:
+    {{ commandName }} help library

package/data/help/topics/uri.jinja

@@ -8,7 +8,8 @@ Purpose:
   Use this page to choose a target, understand scope/object behavior, and select retrieval shape.
 
 Archive locator:
-  - Archive/object command URIs must contain a `.wikg` locator.
+  - Normal archive/object command URIs contain a `.wikg` locator.
+  - Library URIs and local runtime URIs are separate URI families and do not contain `.wikg` locators.
   - Do not pass a bare filesystem path as a command target.
     /Users/me/book.wikg -> wikg:///Users/me/book.wikg
     ./book.wikg -> wikg://book.wikg
@@ -19,17 +20,31 @@ Archive locator:
   - Home archive locators may start with `wikg://~/`; `~` is expanded only in that leading form.
   - The first path segment ending in `.wikg` is the archive/object boundary.
 
+Library locators:
+  - `wikg://lib` addresses the default library.
+  - `wikg://lib/<lib-id>` addresses a non-default library.
+  - Naked library scopes enumerate library-wide objects; `--query` on a naked library scope searches library-wide objects through the library index.
+  - Use explicit object lenses such as `/entity`, `/triple`, `/chapter`, or `/chunk` for archive object search.
+  - `wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
+  - `wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
+  - Add ordinary archive object suffixes after the trailing slash to query a managed archive:
+    wikg://lib/arc/<archive-id>/chapter
+    wikg://lib/arc/<archive-id>/entity
+    wikg://lib/arc/<archive-id>/triple
+  - Library-wide scopes such as `wikg://lib/entity` query the aggregate library index.
+  - Read `{{ commandName }} help library` before managing registry, membership, path binding, or library index lifecycle.
+
 Short and located URIs:
   Commands may return short object URIs without local file paths:
-    wikg://chapter/3/title
-    wikg://chapter/3/source#4..8
+    wikg://chapter/part/title
+    wikg://chapter/part/source#4..8
     wikg://chunk/12
     wikg://entity/Q8018
     wikg://triple/Q8018/discusses/Q123
   Returned short URIs are archive-relative handles, not complete command targets.
   Add the archive locator before passing them back to commands:
     wikg://book.wikg/entity/Q8018
-    wikg:///books/book.wikg/chapter/3/source#4..8
+    wikg:///books/book.wikg/chapter/part/source#4..8
 
 Command routing:
   - `{{ commandName }} <scope-uri>` enumerates objects.
@@ -50,21 +65,27 @@ Common command shapes:
   {{ commandName }} <archive-uri> export --output-format <format>
   {{ commandName }} <archive-uri> inspect
   {{ commandName }} transform [options]
+  {{ commandName }} wikg://lib --help
+  {{ commandName }} wikg://lib/entity --query <query>
+  {{ commandName }} wikg://lib/arc/<archive-id>/entity --query <query>
   {{ commandName }} wikg://local/job
   {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost
   {{ commandName }} wikg://local/job/<job-id>
-  {{ commandName }} <object-uri> related
-  {{ commandName }} <object-uri> evidence
-  {{ commandName }} <object-uri> pack --budget 5000
 
 Scope URIs:
   Scope URIs enumerate objects by default. With `--query <query>`, they apply keyword retrieval within that scope.
+  A chapter URI used as a scope covers that chapter's full subtree by default.
+  Add `--depth <N>` to limit chapter subtree expansion:
+    - no `--depth`: full subtree
+    - `--depth 0`: only the current chapter, or root-level chapters for `<archive-uri>/chapter`
+    - `--depth 1`: current/root-level chapters plus direct children
+  `--depth` must include a non-negative integer value; naked `--depth`, negative values, and non-integers are invalid.
     wikg://book.wikg
     wikg://book.wikg/chapter
-    wikg://book.wikg/chapter/3
-    wikg://book.wikg/chapter/3/chunk
-    wikg://book.wikg/chapter/3/entity
-    wikg://book.wikg/chapter/3/triple
+    wikg://book.wikg/chapter/part
+    wikg://book.wikg/chapter/part/chunk
+    wikg://book.wikg/chapter/part/entity
+    wikg://book.wikg/chapter/part/triple
     wikg://book.wikg/chunk
     wikg://book.wikg/entity
     wikg://book.wikg/triple
@@ -74,15 +95,15 @@ Scope URIs:
 
 Object URIs:
   Object URIs read one object by default.
-    wikg://book.wikg/chapter/3/title
-    wikg://book.wikg/chapter/3/state
-    wikg://book.wikg/chapter/3/source
-    wikg://book.wikg/chapter/3/source#4..8
-    wikg://book.wikg/chapter/3/summary
-    wikg://book.wikg/chapter/3/summary#4..8
-    wikg://book.wikg/chapter/3/chunk/12
-    wikg://book.wikg/chapter/3/entity/Q8018
-    wikg://book.wikg/chapter/3/triple/Q8018/discusses/Q123
+    wikg://book.wikg/chapter/part/title
+    wikg://book.wikg/chapter/part/state
+    wikg://book.wikg/chapter/part/source
+    wikg://book.wikg/chapter/part/source#4..8
+    wikg://book.wikg/chapter/part/summary
+    wikg://book.wikg/chapter/part/summary#4..8
+    wikg://book.wikg/chapter/part/chunk/12
+    wikg://book.wikg/chapter/part/entity/Q8018
+    wikg://book.wikg/chapter/part/triple/Q8018/discusses/Q123
     wikg://book.wikg/chunk/12
     wikg://book.wikg/entity/Q8018
     wikg://book.wikg/entity/Q8018/wikipage
@@ -99,9 +120,12 @@ Triple pattern scopes:
   A complete triple URI with concrete subject, predicate, and object is an object URI.
 
 Object boundaries:
-  - `chapter/<id>` is a scope, not an object.
-  - `chapter/<id>/title` is the queryable chapter title object.
+  - `chapter/<path>` is a scope, not an object.
+  - `chapter/<path>/title` is the queryable chapter title object.
   - Whole `source` and `summary` objects are readable text streams, not collection scopes.
+  - Chapter-qualified scope URIs such as `<chapter-uri>/chunk`, `<chapter-uri>/entity`, and `<chapter-uri>/triple` expand to the chapter subtree and support `--depth`.
+  - Chapter-qualified resource and object URIs such as `/source`, `/summary`, `/title`, `/state`, `/chunk/<id>`, `/entity/<qid>`, and complete `/triple/<subject>/<predicate>/<object>` do not expand to subtrees and do not support `--depth`.
+  - `move`, `remove`, and `reset` are chapter node maintenance predicates; they target the chapter node itself, not the subtree. Use `remove --recursive` for explicit recursive deletion.
   - Ranged fragments such as `/source#4..8` and `/summary#4..8` are structured range objects.
   - Source and summary range numbers are 1-based and inclusive. `/source#1..2` means the first two source sentences.
   - Source text is the grounding material. `evidence` is not available for source, summary, or chapter scope URIs.
@@ -126,13 +150,13 @@ Lens selection:
   - `/chunk` targets Reading Graph chunks.
   - `/entity` targets grounded entities.
   - `/triple` targets Knowledge Graph relations.
-  - `chapter/<id>` is a scope; `--query` over chapter titles returns `chapter/<id>/title` objects.
+  - `chapter/<path>` is a scope; `--query` over chapter titles returns `chapter/<path>/title` objects.
 
 Literal source passages:
   Use `--query` on the narrowest useful scope when the task is to find source wording or passages mentioning a literal term:
     {{ commandName }} <archive-uri> --query "term"
-    {{ commandName }} <archive-uri>/chapter/<id> --query "term"
-    {{ commandName }} <archive-uri>/chapter/<id>/source#20..30
+    {{ commandName }} <archive-uri>/chapter/<path> --query "term"
+    {{ commandName }} <archive-uri>/chapter/<path>/source#20..30
 
 Entity-grounded evidence:
   Use entity evidence when you already have an entity URI or QID and need grounded mentions, aliases, translations, variants, or source-backed support:
@@ -143,6 +167,7 @@ Entity-grounded evidence:
 Pagination:
   - Use default paging or `--limit <n>` while exploring.
   - Use `{{ commandName }} next <cursor>` to continue a paged result.
+  - Use `{{ commandName }} next <uri> <cursor>` when you want the cursor's stored index scope checked against the archive or library URI you expect.
   - Use `--all` only when you intentionally need every item from the selected scope.
   - Prefer the narrowest scope before using `--all`.
   - Read `{{ commandName }} help format` before choosing text, `--json`, `--jsonl`, or `--all --jsonl` for machine consumption.
@@ -158,6 +183,7 @@ Recovery hints:
     {{ commandName }} help readiness
     {{ commandName }} help runtime
   - URI rejected: convert bare filesystem paths to Wiki Graph URIs, and prepend the archive locator to short object URIs.
+  - Library URI rejected: non-default libraries use wikg://lib/<lib-id>; archive members use <lib-scope>/arc/<archive-id>.
   - Help did not appear: append `--help` to the URI or URI-bound predicate you are trying to inspect.
 
 Job URIs:
@@ -176,3 +202,5 @@ Related help:
     {{ commandName }} help format
   - Local jobs, cache, logs, and runtime debugging:
     {{ commandName }} help runtime
+  - Library registry, membership, path binding, and aggregate index:
+    {{ commandName }} help library

package/dist/api/app.d.ts

@@ -0,0 +1,87 @@
+import { LanguageModel } from 'ai';
+import { Language } from '../runtime/common/language.js';
+import { WikiGraphProgressCallback } from '../runtime/progress/types.js';
+export { DigestProgressEvent, SerialDiscoveryItem, SerialProgressEvent, SerialsDiscoveredEvent, WikiGraphOperation, WikiGraphProgressEvent, WikiGraphProgressEventType } from '../runtime/progress/types.js';
+import { DigestDocumentSessionOptions } from './digest.js';
+import { WikiGraphArchive } from './wiki-graph-archive.js';
+import { ChapterStage } from '../document/chapter/types.js';
+import '../text/source/meta.js';
+import 'zod';
+import '../runtime/common/llm-scope.js';
+import '../text/reader/types.js';
+import '../text/reader/attention/core.js';
+import '../text/reader/chunk-batch/types.js';
+import '../external/llm/client/core.js';
+import '../external/llm/context.js';
+import '../external/llm/cache.js';
+import '../external/llm/types.js';
+import '../document/types.js';
+import '../text/reader/segment/types.js';
+import '../text/source/toc.js';
+import '../text/source/types.js';
+import '../document/directory/types.js';
+import '../document/database.js';
+import 'sqlite3';
+import '../document/text-streams/serial.js';
+import '../document/text-streams/draft.js';
+import '../document/text-streams/types.js';
+import '../document/stores/chunk.js';
+import '../document/stores/types.js';
+import '../document/stores/fragment-group.js';
+import '../document/stores/graph-build-parameter.js';
+import '../document/stores/mention-link.js';
+import '../document/stores/mention.js';
+import '../document/stores/object-metadata.js';
+import '../document/stores/reading-edge.js';
+import '../document/stores/serial.js';
+import '../document/stores/snake/chunk.js';
+import '../document/stores/snake/core.js';
+import '../document/stores/snake/edge.js';
+import './types.js';
+
+interface WikiGraphLLMOptions {
+    readonly cacheDirPath?: string;
+    readonly concurrent?: number;
+    readonly logDirPath?: string;
+    readonly model: LanguageModel;
+    readonly retryIntervalSeconds?: number;
+    readonly retryTimes?: number;
+    readonly stream?: boolean;
+    readonly temperature?: number | readonly number[];
+    readonly timeout?: number;
+    readonly topP?: number | readonly number[];
+}
+interface WikiGraphOptions {
+    readonly debugLogDirPath?: string;
+    readonly llm?: LanguageModel | WikiGraphLLMOptions;
+    readonly verbose?: boolean;
+}
+type WikiGraphOpenSessionOptions = DigestDocumentSessionOptions;
+interface WikiGraphSourceSessionOptions extends DigestDocumentSessionOptions {
+    readonly extractionPrompt?: string;
+    readonly onProgress?: WikiGraphProgressCallback;
+    readonly path: string;
+    readonly targetStage?: ChapterStage;
+    readonly userLanguage?: Language;
+}
+interface WikiGraphTextStreamSessionOptions extends DigestDocumentSessionOptions {
+    readonly bookLanguage?: string | null;
+    readonly extractionPrompt?: string;
+    readonly onProgress?: WikiGraphProgressCallback;
+    readonly sourceFormat?: "markdown" | "txt";
+    readonly stream: AsyncIterable<string> | Iterable<string>;
+    readonly targetStage?: ChapterStage;
+    readonly title?: string | null;
+    readonly userLanguage?: Language;
+}
+declare class WikiGraph {
+    #private;
+    constructor(options: WikiGraphOptions);
+    digestEpubSession<T>(options: WikiGraphSourceSessionOptions, operation: (digest: WikiGraphArchive) => Promise<T> | T): Promise<T>;
+    digestMarkdownSession<T>(options: WikiGraphSourceSessionOptions, operation: (digest: WikiGraphArchive) => Promise<T> | T): Promise<T>;
+    digestTextStreamSession<T>(options: WikiGraphTextStreamSessionOptions, operation: (digest: WikiGraphArchive) => Promise<T> | T): Promise<T>;
+    digestTxtSession<T>(options: WikiGraphSourceSessionOptions, operation: (digest: WikiGraphArchive) => Promise<T> | T): Promise<T>;
+    openSession<T>(path: string, operation: (digest: WikiGraphArchive) => Promise<T> | T, options?: WikiGraphOpenSessionOptions): Promise<T>;
+}
+
+export { WikiGraph, type WikiGraphLLMOptions, type WikiGraphOpenSessionOptions, type WikiGraphOptions, WikiGraphProgressCallback, type WikiGraphSourceSessionOptions, type WikiGraphTextStreamSessionOptions };

package/dist/api/app.js

@@ -0,0 +1,137 @@
+import { resolveDataDirPath } from "../runtime/common/data-dir.js";
+import { withLoggingContext } from "../runtime/common/logging.js";
+import { LLM } from "../external/llm/index.js";
+import {
+  digestEpubSession,
+  digestMarkdownSession,
+  digestTextStreamSession,
+  digestTxtSession
+} from "./digest.js";
+import { createDefaultWikiGraphSampling } from "./llm-sampling.js";
+import { WikiGraphArchiveFile } from "../storage/wikg/index.js";
+import { resolveExtractionPrompt } from "./prompts.js";
+const DATA_DIR_PATH = resolveDataDirPath();
+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;
+}
+export {
+  WikiGraph
+};
+//# sourceMappingURL=app.js.map

package/dist/api/app.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/app.ts"],"sourcesContent":["import type { LanguageModel } from \"ai\";\n\nimport { resolveDataDirPath } from \"../runtime/common/data-dir.js\";\nimport type { Language } from \"../runtime/common/language.js\";\nimport type { WikiGraphScope } from \"../runtime/common/llm-scope.js\";\nimport { withLoggingContext } from \"../runtime/common/logging.js\";\nimport { LLM } from \"../external/llm/index.js\";\nimport type {\n  DigestProgressEvent,\n  SerialDiscoveryItem,\n  SerialsDiscoveredEvent,\n  SerialProgressEvent,\n  WikiGraphProgressCallback,\n  WikiGraphProgressEvent,\n  WikiGraphProgressEventType,\n  WikiGraphOperation,\n} from \"../runtime/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 \"../storage/wikg/index.js\";\nimport type { WikiGraphArchive } from \"./wiki-graph-archive.js\";\nimport type { ChapterStage } from \"./chapter/index.js\";\nimport { resolveExtractionPrompt } from \"./prompts.js\";\n\nconst DATA_DIR_PATH = resolveDataDirPath();\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"],"mappings":"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","names":[]}

package/dist/api/chapter/advance.d.ts

@@ -0,0 +1,36 @@
+import { Document } from '../../document/directory/types.js';
+import { AdvanceChapterStagesOptions, AdvanceChapterStagesResult } from './types.js';
+import '../../text/source/meta.js';
+import 'zod';
+import '../../text/source/toc.js';
+import '../../text/source/types.js';
+import '../../document/database.js';
+import 'sqlite3';
+import '../../document/types.js';
+import '../../document/text-streams/serial.js';
+import '../../document/text-streams/draft.js';
+import '../../document/text-streams/types.js';
+import '../../document/stores/chunk.js';
+import '../../document/stores/types.js';
+import '../../document/stores/fragment-group.js';
+import '../../document/stores/graph-build-parameter.js';
+import '../../document/stores/mention-link.js';
+import '../../document/stores/mention.js';
+import '../../document/stores/object-metadata.js';
+import '../../document/stores/reading-edge.js';
+import '../../document/stores/serial.js';
+import '../../document/stores/snake/chunk.js';
+import '../../document/stores/snake/core.js';
+import '../../document/stores/snake/edge.js';
+import '../../runtime/common/language.js';
+import '../../runtime/common/llm-scope.js';
+import '../../external/llm/client/core.js';
+import '../../external/llm/context.js';
+import '../../external/llm/cache.js';
+import '../../external/llm/types.js';
+import 'ai';
+import '../../document/chapter/types.js';
+
+declare function advanceChapterStages(document: Document, options: AdvanceChapterStagesOptions): Promise<AdvanceChapterStagesResult>;
+
+export { advanceChapterStages };