@bendyline/gezel-knowledge 1.2.1 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +175 -49
  2. package/dist/index.js +1462 -201
  3. package/package.json +2 -2
package/dist/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { CatalogDocument, KnowledgeEmbeddingProfile, KnowledgeChunkingProfile, KnowledgeCatalogManifest, GezkIndexSchemaVersion, KnowledgeRegistryIndex, KnowledgeRegistryEntry } from '@bendyline/gezk';
2
- export { BODY_CODEC_MIN_BYTES, CatalogDocument, GEZK_APPLICATION_ID, GEZK_FORMAT_GENERATIONS, GEZK_FORMAT_VERSION, GEZK_INDEX_SCHEMA_VERSION, GEZK_MIME_TYPE, GEZK_SUPPORTED_FORMAT_VERSIONS, GEZK_SUPPORTED_INDEX_SCHEMA_VERSIONS, GezkFormatVersion, GezkIndexSchemaVersion, KnowledgeCatalogManifest, KnowledgeChunkingProfile, KnowledgeEmbeddingProfile, KnowledgeRegistryEntry, KnowledgeRegistryIndex, LICENSE_NOTICE_PATH, MANIFEST_PATH, MAX_KNOWLEDGE_DOCUMENT_BYTES, MAX_KNOWLEDGE_DOCUMENT_META_BYTES, MAX_KNOWLEDGE_TOPIC_DEPTH, MIMETYPE_PATH, README_PATH, ROUTER_DB_PATH, ROUTER_DDL, SHARD_DDL, SOURCE_NOTICES_PATH, ZIP_FIXED_MTIME, canonicalizeJson, centerVector, documentSlug, isSupportedFormatVersion, isSupportedIndexSchemaVersion, l2Normalize, quantizeBinary, quantizeBinaryForProfile, quantizeInt8, rerankScore } from '@bendyline/gezk';
1
+ import * as _bendyline_gezk from '@bendyline/gezk';
2
+ import { CatalogDocument, KnowledgeEmbeddingProfile, KnowledgeChunkingProfile, KnowledgeCatalogManifest, GezkIndexSchemaVersion, KnowledgeLocation, KnowledgeRadius, KnowledgeRegistryIndex, KnowledgeRegistryEntry } from '@bendyline/gezk';
3
+ export { BODY_CODEC_MIN_BYTES, CatalogDocument, GEZK_APPLICATION_ID, GEZK_FORMAT_GENERATIONS, GEZK_FORMAT_VERSION, GEZK_INDEX_SCHEMA_VERSION, GEZK_MIME_TYPE, GEZK_SUPPORTED_FORMAT_VERSIONS, GEZK_SUPPORTED_INDEX_SCHEMA_VERSIONS, GezkFormatVersion, GezkIndexSchemaVersion, KnowledgeCatalogManifest, KnowledgeChunkingProfile, KnowledgeEmbeddingProfile, KnowledgeRegistryEntry, KnowledgeRegistryIndex, KnowledgeTocReference, LICENSE_NOTICE_PATH, MANIFEST_PATH, MAX_KNOWLEDGE_DOCUMENT_BYTES, MAX_KNOWLEDGE_DOCUMENT_META_BYTES, MAX_KNOWLEDGE_TOPIC_DEPTH, MIMETYPE_PATH, README_PATH, ROUTER_DB_PATH, ROUTER_DDL, SHARD_DDL, SOURCE_NOTICES_PATH, ZIP_FIXED_MTIME, canonicalizeJson, centerVector, documentSlug, isSupportedFormatVersion, isSupportedIndexSchemaVersion, l2Normalize, quantizeBinary, quantizeBinaryForProfile, quantizeInt8, rerankScore } from '@bendyline/gezk';
3
4
  import { KnowledgeTrustAnchor } from '@bendyline/gezk/node';
4
5
  export { KnowledgeTrustAnchor, ManifestSignatureVerdict, chunkContentHash, chunkUid, generateKnowledgeSigningKeyPair, knowledgeKeyId, manifestSigningPayload, signManifest, signRegistryIndex, verifyManifestSignature, verifyRegistryIndex } from '@bendyline/gezk/node';
5
6
  import { DatabaseSync as DatabaseSync$1 } from 'node:sqlite';
@@ -78,8 +79,16 @@ type ChunkerOptions = CharChunkerOptions | TokenChunkerOptions;
78
79
  /** Split markdown into heading-aware, bounded, overlapping chunks. */
79
80
  declare function chunkMarkdownProfile(md: string, opts: ChunkerOptions): MarkdownChunk[];
80
81
 
82
+ interface CompileAsset {
83
+ /** Archive path, assets/…, matching the format's asset path grammar. */
84
+ path: string;
85
+ /** Exactly one of absPath / content. */
86
+ absPath?: string;
87
+ content?: Buffer;
88
+ }
89
+
81
90
  /**
82
- * `.gezk` compiler (gezk 0.6; spec in bendyline/gezk). One owner of normalization, chunk
91
+ * `.gezk` compiler (gezk 0.7; spec in bendyline/gezk). One owner of normalization, chunk
83
92
  * ids, embedding-profile conformance, SQLite schema, shard assignment,
84
93
  * centroid routing, and deterministic archive layout — the CLI's Markdown
85
94
  * adapter and Qualla's Wikipedia adapter both feed this API.
@@ -104,13 +113,6 @@ interface CompileTopic {
104
113
  description?: string;
105
114
  sortKey?: string;
106
115
  }
107
- interface CompileAsset {
108
- /** Archive path, `assets/…`, matching the format's asset path grammar. */
109
- path: string;
110
- /** Exactly one of `absPath` / `content`. */
111
- absPath?: string;
112
- content?: Buffer;
113
- }
114
116
  interface CompileKnowledgeCatalogOptions {
115
117
  catalog: {
116
118
  id: string;
@@ -189,6 +191,13 @@ interface CompileKnowledgeCatalogOptions {
189
191
  * and declared in `manifest.files` like every other entry.
190
192
  */
191
193
  assets?: CompileAsset[];
194
+ /**
195
+ * Invalid image content (type mismatch, oversized file, or active SVG)
196
+ * fails by default. `warn` omits it and replaces its body references with
197
+ * their text. Invalid paths, duplicates, and aggregate limits still fail.
198
+ */
199
+ invalidAssets?: 'error' | 'warn';
200
+ onWarning?: (message: string) => void;
192
201
  /**
193
202
  * Last touch before the manifest is archived — the signing seam
194
203
  * (signatures/signing.ts `signManifest`). Must only add/replace the
@@ -337,34 +346,31 @@ interface CatalogDb {
337
346
  declare function openCatalogDatabase(absPath: string): CatalogDb;
338
347
 
339
348
  /**
340
- * One mounted catalog: the router database plus lazily opened shards, and
341
- * the two-stage query flow (the gezk spec §8 and §9):
342
- *
343
- * embed query (caller) → centroid routing → per shard: sign-bit scan
344
- * top-K → int8 rerank → fuse.
345
- *
346
- * Stage 1 runs in memory: a shard's sign-bit rows are loaded once into a
347
- * contiguous array (9.6 MB for a full 200k-chunk shard) and scanned with
348
- * the float query (`asymmetricTopK`), so no vector extension is needed to
349
- * read a catalog. The catalog's own profile echo says how its bits were
350
- * derived: a `centered-sign` profile's bits come from `vector − center`, so
351
- * the query is centered the same way before the scan. The int8 rerank is
352
- * identical for both kinds of bits.
353
- *
354
- * The handle is synchronous (node:sqlite) and single-threaded by design —
355
- * the daemon confines every handle to its knowledge worker thread; the CLI
356
- * and tests call it directly.
349
+ * Read-only document point index. The router's ordinary SQLite latitude and
350
+ * longitude indexes provide conservative candidates; the portable gezk
351
+ * spherical predicate decides membership before ranking or pagination.
352
+ * The explicit Qualla adapter keeps already-published 0.6 regional archives
353
+ * useful without interpreting arbitrary producer metadata as coordinates.
357
354
  */
358
355
 
356
+ interface SpatialMatch {
357
+ distanceMeters: number;
358
+ matchedLocation: KnowledgeLocation;
359
+ }
360
+ interface DocumentLocationRow {
361
+ documentId: string;
362
+ location: KnowledgeLocation;
363
+ }
364
+
359
365
  interface CatalogTopic {
360
366
  id: string;
361
367
  parentId: string | null;
362
368
  name: string;
363
369
  description: string | null;
364
370
  sortKey: string;
365
- /** Documents filed directly at this topic (`topics.document_count`). */
371
+ /** Unique documents listed directly at this topic, including shared references. */
366
372
  documentCount: number;
367
- /** Direct plus every descendant topic's documents (computed at read time). */
373
+ /** Unique documents in this topic and its descendants, deduplicated at read time. */
368
374
  totalDocumentCount: number;
369
375
  }
370
376
  interface CatalogDocumentMeta {
@@ -373,7 +379,7 @@ interface CatalogDocumentMeta {
373
379
  slug: string;
374
380
  summary: string | null;
375
381
  language: string;
376
- /** The topic the document is filed at — the leaf of its path on 0.6, the root on 0.5. */
382
+ /** Listing placement for a scoped page; primary topic for getDocument/search/global listings. */
377
383
  topicId: string;
378
384
  /** Listing position among the documents of its topic; null when unordered. */
379
385
  ordinal: number | null;
@@ -383,6 +389,7 @@ interface CatalogDocumentMeta {
383
389
  attribution: Record<string, string> | null;
384
390
  /** Producer-defined metadata (`meta_json`), opaque to the reader. */
385
391
  meta: Record<string, unknown> | null;
392
+ locations?: KnowledgeLocation[];
386
393
  }
387
394
  interface CatalogAssetInfo {
388
395
  /** Archive path under `assets/`. */
@@ -412,11 +419,19 @@ interface ShardInfo {
412
419
  path: string;
413
420
  chunkCount: number;
414
421
  }
422
+ /**
423
+ * Shards a single-catalog search adds for the pages its query names by
424
+ * title (`titleRouteShards`), on top of the centroid-routed budget.
425
+ */
426
+ declare const TITLE_ROUTE_SHARDS = 1;
415
427
  declare class CatalogHandle {
416
428
  readonly rootDir: string;
417
429
  private readonly router;
418
430
  private readonly connections;
419
431
  private readonly bitIndexes;
432
+ /** `shard path \0 phrase` → rows the phrase matches in that shard's `fts_chunks`. */
433
+ private readonly chunkTermRows;
434
+ private readonly spatial;
420
435
  private assetsByPath;
421
436
  /** Lazily parsed from the profile echo; `undefined` until first needed. */
422
437
  private binaryCenterCache;
@@ -443,6 +458,13 @@ declare class CatalogHandle {
443
458
  * the row index IS the id — so a gap is a corrupt shard, not a sparse one.
444
459
  */
445
460
  private shardBits;
461
+ /**
462
+ * Load the next shard's sign bits that are not resident yet, if they fit
463
+ * the resident budget. False when nothing is left to load. One shard per
464
+ * call, so a host can keep answering queries between shards while it warms
465
+ * a large catalog, and never evicts a shard it loaded a moment ago.
466
+ */
467
+ prewarmNextShard(): boolean;
446
468
  /**
447
469
  * The stage-1 center the catalog's bits were derived with (a
448
470
  * `centered-sign` profile), or null for plain sign bits. Read from the
@@ -476,9 +498,26 @@ declare class CatalogHandle {
476
498
  documents: CatalogDocumentMeta[];
477
499
  total: number;
478
500
  };
501
+ /** A reference is a placement, not a duplicate result or a redirect page. */
502
+ private sharedDocumentsPage;
503
+ /** Integrity facts kept separate from browse counts, which include shared references. */
504
+ tocIntegrity(): {
505
+ placements: number;
506
+ invalidReferences: number;
507
+ missingPrimary: number;
508
+ incorrectCounts: number;
509
+ duplicateReferences: number;
510
+ };
479
511
  getDocument(id: string): (CatalogDocumentMeta & {
480
512
  markdown: string;
481
513
  }) | null;
514
+ /**
515
+ * One passage by its citation id (`knowledge://…#chunk=<uid>`), from the
516
+ * shard the document's chunks live in. Null when the document or the
517
+ * passage is not in this catalog, which is what a fabricated or stale
518
+ * citation looks like.
519
+ */
520
+ getChunk(documentId: string, chunkUid: string): Omit<CatalogChunkHit, 'cosine' | 'source'> | null;
482
521
  /** Documents whose `topic_id` names no declared topic (a validator check). */
483
522
  documentsWithUndeclaredTopic(): number;
484
523
  /**
@@ -505,11 +544,27 @@ declare class CatalogHandle {
505
544
  assets(): CatalogAssetInfo[];
506
545
  /** One declared asset's bytes, or null when the catalog declares no such asset. */
507
546
  readAsset(path: string): CatalogAssetRead | null;
547
+ private documentMeta;
548
+ documentLocations(documentId: string): KnowledgeLocation[];
549
+ documentLocationRows(): DocumentLocationRow[];
550
+ spatialIntegrity(): {
551
+ hasTable: boolean;
552
+ manifest: _bendyline_gezk.KnowledgeSpatialManifest;
553
+ };
554
+ spatialMatches(radius: KnowledgeRadius): Map<string, SpatialMatch>;
555
+ nearbyDocuments(radius: KnowledgeRadius, opts?: {
556
+ offset?: number;
557
+ limit?: number;
558
+ }): {
559
+ documents: Array<CatalogDocumentMeta & SpatialMatch>;
560
+ total: number;
561
+ };
562
+ shardsForDocuments(ids: ReadonlySet<string>): number[];
508
563
  /**
509
564
  * Catalog-wide title/summary/alias FTS — always runs regardless of routing.
510
565
  * Name-first: an exact title, then title-weighted BM25 (see fts-query.ts).
511
566
  */
512
- searchDocumentsFts(query: string, limit?: number): Array<{
567
+ searchDocumentsFts(query: string, limit?: number, allowedDocumentIds?: ReadonlySet<string>): Array<{
513
568
  documentId: string;
514
569
  rank: number;
515
570
  }>;
@@ -533,8 +588,32 @@ declare class CatalogHandle {
533
588
  shardId: number;
534
589
  score: number;
535
590
  }>;
536
- /** Top-S shard ids within THIS catalog (single-catalog callers, tests). */
537
- routeShards(queryVector: Float32Array, shardBudget: number): number[];
591
+ /**
592
+ * Top-S shard ids within THIS catalog (single-catalog callers, tests).
593
+ * With the raw `query`, also the shard of the page it names by title
594
+ * (`titleRouteShards`), so the result can exceed S by `TITLE_ROUTE_SHARDS`.
595
+ */
596
+ routeShards(queryVector: Float32Array, shardBudget: number, query?: string): number[];
597
+ /**
598
+ * Title-assisted routing: the shards holding the pages `query` names by
599
+ * title (`namedTitleMatches`), most specific name first, at most `limit`
600
+ * distinct shards. Centroid routing compares a question with averages of
601
+ * whole shards, and e5 scores those in a band a few hundredths wide, so
602
+ * the shard holding the very page a question names can rank 8th of 10:
603
+ * "Who were the members of ABBA?" never reached the ABBA article in the
604
+ * Wikipedia music catalog. Its title does — the vector arm scans that
605
+ * shard too. Measured on the 10-shard music and film-tv catalogs, one such
606
+ * shard lifted end-to-end recall@8 on "What is <title>?" questions from
607
+ * 86% to 92% and 84% to 91%, at about 0.15 extra shard scans per query.
608
+ *
609
+ * `score` is the named match's specificity (fts-query.ts), comparable
610
+ * across catalogs closely enough for the daemon to choose which catalogs'
611
+ * shards to add when several name a page. Empty on any FTS error.
612
+ */
613
+ titleRouteShards(query: string, limit: number): Array<{
614
+ shardId: number;
615
+ score: number;
616
+ }>;
538
617
  /**
539
618
  * Two-stage semantic search over the routed shards: sign-bit scan
540
619
  * (stage 1) → int8 rerank (stage 2). Sequential by design (§9).
@@ -542,14 +621,19 @@ declare class CatalogHandle {
542
621
  searchSemantic(queryVector: Float32Array, opts?: {
543
622
  shardBudget?: number;
544
623
  finalK?: number;
624
+ allowedDocumentIds?: ReadonlySet<string>;
625
+ /** The raw query text: adds the shard of the page it names (`routeShards`). */
626
+ query?: string;
545
627
  }): CatalogChunkHit[];
546
628
  /**
547
629
  * The scan stage against an EXPLICIT shard list — what the daemon calls
548
630
  * after global cross-catalog routing has already spent the S budget.
549
631
  */
550
- searchShards(queryVector: Float32Array, shardIds: number[], finalK: number): CatalogChunkHit[];
632
+ searchShards(queryVector: Float32Array, shardIds: number[], finalK: number, allowedDocumentIds?: ReadonlySet<string>): CatalogChunkHit[];
551
633
  /** Chunk-body FTS over the routed shards (explicit search only). */
552
- searchChunksFts(query: string, shardIds: number[], limitPerShard?: number): CatalogChunkHit[];
634
+ searchChunksFts(query: string, shardIds: number[], limitPerShard?: number, allowedDocumentIds?: ReadonlySet<string>): CatalogChunkHit[];
635
+ /** Rows of one shard's `fts_chunks` an FTS5 phrase matches — what `selectiveFtsQuery` prunes on. */
636
+ private chunkFtsRows;
553
637
  /**
554
638
  * Embedder-free integrity smoke: chunk 1's own bit vector must be its own
555
639
  * nearest neighbor — proves the shard's vectors load and scan. Returns
@@ -635,7 +719,40 @@ interface AsymmetricHit {
635
719
  * plain `sign` profile the unit query. The bits are whatever the catalog
636
720
  * stored; this function does not know or care which.
637
721
  */
638
- declare function asymmetricTopK(index: ShardBitIndex, query: ArrayLike<number>, k: number): AsymmetricHit[];
722
+ declare function asymmetricTopK(index: ShardBitIndex, query: ArrayLike<number>, k: number, eligibleChunkIds?: ReadonlySet<number>): AsymmetricHit[];
723
+
724
+ /**
725
+ * Words that carry no subject in a search request. Dropping one from an FTS5
726
+ * OR query is safe: it can only remove hits that matched nothing else, and
727
+ * anything holding a distinctive term still ranks.
728
+ *
729
+ * One list for every keyword-search path — the project index's query builder
730
+ * and token scorers in the service, and the knowledge-catalog reader here.
731
+ * It lives in this package because the reader cannot import the service.
732
+ * There were three lists once: a 24-word one behind the project index's FTS5
733
+ * query, a 14-word one behind area-summary token coverage, and the catalog
734
+ * reader's function words. Neither project list covered the vocabulary of an
735
+ * ordinary request, so "Can you create a PowerPoint about France" reached
736
+ * FTS5 as `"can"* OR "create"* OR "powerpoint"* OR "about"* OR "france"*`.
737
+ * In the shared library `france` matched nothing at all while
738
+ * `can`/`about`/`create` matched 66/25/30 rows, so ranking was decided
739
+ * entirely by the filler: the top document hit was a career memoir, and the
740
+ * top symbol hit was a heading called "All About DocBlocks" whose only
741
+ * matched token was `about`. The catalog reader kept `tell`, `please` and
742
+ * `help` in "Can you tell me how to integrate Azure search with blob
743
+ * storage?".
744
+ *
745
+ * Callers fall back to every token when a query is nothing but these words,
746
+ * so "how to" and a bare search for "create" still search for what was typed.
747
+ *
748
+ * Judgment call worth knowing about: the request verbs `create` and `make`
749
+ * are stopwords, while `build`, `fix`, `read`, `write`, `update`, `delete`
750
+ * and `show` are not. The first two are how a user says "produce a thing" and
751
+ * carry no subject; the rest name real work and real symbols in a codebase.
752
+ *
753
+ * Lowercase; compare against a lowercased token.
754
+ */
755
+ declare const QUERY_STOP_WORDS: ReadonlySet<string>;
639
756
 
640
757
  /**
641
758
  * Provenance stamped into every manifest this package compiles. Only the
@@ -691,8 +808,8 @@ declare function runDuckdbScript(cli: DuckdbCli, sql: string): Promise<string>;
691
808
  * bytes.
692
809
  */
693
810
 
694
- /** 3: the bit-rule metadata follows the profile's binary method (was always plain sign). */
695
- declare const PARQUET_EXPORT_VERSION = 3;
811
+ /** 4: document-locations companion, including the explicit legacy Qualla adapter. */
812
+ declare const PARQUET_EXPORT_VERSION = 4;
696
813
  type ParquetExportSource = {
697
814
  archivePath: string;
698
815
  } | {
@@ -716,7 +833,7 @@ type ParquetExportProgress = {
716
833
  phase: 'write';
717
834
  file: string;
718
835
  };
719
- type ParquetTable = 'documents' | 'chunks' | 'topics';
836
+ type ParquetTable = 'documents' | 'chunks' | 'topics' | 'document_locations';
720
837
  interface ParquetExportFile {
721
838
  /** Relative to `outDir`, forward slashes. */
722
839
  path: string;
@@ -1028,6 +1145,8 @@ declare function transformersGraphOptions(onnxFile: string): {
1028
1145
  } | null;
1029
1146
  declare function createProfileEmbedder(profile: KnowledgeEmbeddingProfile, opts?: {
1030
1147
  cacheDir?: string;
1148
+ /** Read cached model files only; never initiate a download. */
1149
+ localFilesOnly?: boolean;
1031
1150
  /**
1032
1151
  * onnxruntime session options (e.g. `{ intraOpNumThreads }`), passed
1033
1152
  * through to the pipeline. Worker pools use this to divide cores between
@@ -1052,7 +1171,7 @@ declare function createProfileEmbedder(profile: KnowledgeEmbeddingProfile, opts?
1052
1171
  * files, never the disk, so an outline can be checked in a test without a
1053
1172
  * tree on disk.
1054
1173
  */
1055
- type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book';
1174
+ type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book' | 'docfx';
1056
1175
  type OutlineFormat = Exclude<TableOfContentsFormat, 'folders' | 'hugo'>;
1057
1176
  interface OutlineEntry {
1058
1177
  /** Root-relative POSIX path of the Markdown file, extension included. */
@@ -1131,10 +1250,11 @@ declare function parseJupyterBookToc(doc: unknown, tocDir: string, files: readon
1131
1250
  * gets the single root topic the compiler demands.
1132
1251
  *
1133
1252
  * A tree that already carries an outline keeps it: GitBook's `SUMMARY.md`,
1134
- * an `mkdocs.yml` nav and Jupyter Book's `_toc.yml` are read into the same
1135
- * topic tree (`outline.ts`), and Hugo's conventions — `_index.md` section
1136
- * pages, `weight`, `draft` — are honored on top of the folders. A file an
1137
- * outline omits stays in its folder, with a warning, so nothing is lost.
1253
+ * an `mkdocs.yml` nav, Jupyter Book's `_toc.yml` and docfx's per-folder
1254
+ * `toc.yml` files are read into the same topic tree (`outline.ts`,
1255
+ * `docfx.ts`), and Hugo's conventions — `_index.md` section pages,
1256
+ * `weight`, `draft` — are honored on top of the folders. A file an outline
1257
+ * omits stays in its folder, with a warning, so nothing is lost.
1138
1258
  *
1139
1259
  * Front matter carries what a documentation tree knows about itself: the
1140
1260
  * title and summary, an explicit `id`, an `order` (the listing ordinal), a
@@ -1166,7 +1286,10 @@ interface TableOfContentsOptions {
1166
1286
  /**
1167
1287
  * The outline file for `gitbook` (`SUMMARY.md`), `mkdocs` (`mkdocs.yml`)
1168
1288
  * and `jupyter-book` (`_toc.yml`), absolute or relative to the root. By
1169
- * default the root is searched, and for mkdocs its parent as well.
1289
+ * default the root is searched, and for mkdocs its parent as well. For
1290
+ * `docfx` it is the entry TOC (a breadcrumb such as `bread/toc.yml`, or a
1291
+ * root `toc.yml`); by default docfx.json's `breadcrumb_path`, else the
1292
+ * root `toc.yml`.
1170
1293
  */
1171
1294
  path?: string;
1172
1295
  }
@@ -1192,8 +1315,10 @@ interface LoadMarkdownCatalogOptions {
1192
1315
  publisherId: string;
1193
1316
  catalogId: string;
1194
1317
  };
1195
- /** What to do with an image link whose file is missing (default `error`). */
1318
+ /** What to do with an image link whose file is missing (default `error`; `warn` for docfx). */
1196
1319
  missingAssets?: 'error' | 'warn';
1320
+ /** Keep image alt text without resolving or bundling image files. */
1321
+ skipImages?: boolean;
1197
1322
  onWarning?: (message: string) => void;
1198
1323
  }
1199
1324
  /** The docs directory an `mkdocs.yml` names (`docs_dir`, default `docs`), absolute. */
@@ -1201,8 +1326,9 @@ declare function readMkdocsDocsDir(mkdocsPath: string): Promise<string>;
1201
1326
  /**
1202
1327
  * Which outline a tree carries: GitBook's `SUMMARY.md` or Jupyter Book's
1203
1328
  * `_toc.yml` at the root, an `mkdocs.yml` at the root, the project folder
1204
- * or the root's parent, Hugo's `_index.md` section pages anywhere in the
1205
- * tree — else the folders themselves.
1329
+ * or the root's parent, a docfx project (`docfx.json` or a `toc.yml` at the
1330
+ * root), Hugo's `_index.md` section pages anywhere in the tree — else the
1331
+ * folders themselves.
1206
1332
  */
1207
1333
  declare function detectTableOfContents(rootDir: string, projectDir?: string): Promise<TableOfContentsOptions>;
1208
1334
  /**
@@ -1292,4 +1418,4 @@ declare function newerRegistryEntries(registry: KnowledgeRegistryIndex, installe
1292
1418
 
1293
1419
  declare const BUILTIN_KNOWLEDGE_TRUST_ANCHORS: readonly KnowledgeTrustAnchor[];
1294
1420
 
1295
- export { type ArchiveEntry, type ArtifactCheck, type ArtifactRole, type AsymmetricHit, BGE_SMALL_EN_V15_1, BUILTIN_KNOWLEDGE_TRUST_ANCHORS, CENTROID_CHUNKS_PER, CENTROID_KMEANS_MAX_ITER, CENTROID_MAX_PER_SHARD, CENTROID_SAMPLE_MAX, type CatalogAssetInfo, type CatalogAssetRead, type CatalogCheck, type CatalogChunkHit, type CatalogDb, type CatalogDocumentMeta, CatalogHandle, CatalogOpenError, type CatalogTopic, type CatalogValidationReport, type CharChunkerOptions, type ChunkerOptions, type CompileAsset, type CompileKnowledgeCatalogOptions, type CompileReport, type CompileTopic, type DuckdbCli, DuckdbError, EmbedderArtifactError, EmbedderUnavailableError, type FetchKnowledgeRegistryOptions, GEZEL_BGE_SMALL_EN_V15_1, GEZEL_MARKDOWN_CHUNKS_2, GEZEL_MULTILINGUAL_E5_SMALL_1, GEZK_ARCHIVE_LIMITS, GezkArchiveError, type GezkArchiveInspection, type HammingHit, KNOWLEDGE_EMBEDDING_PROFILES, KNOWLEDGE_TOOLCHAIN, type KnowledgeRegistryFetchCode, KnowledgeRegistryFetchError, type LoadMarkdownCatalogOptions, MARKDOWN_CHUNKS_2, MULTILINGUAL_E5_SMALL_1, MULTILINGUAL_E5_SMALL_2, type MarkdownCatalogSource, type MarkdownChunk, type ModelDownloadProgress, type Outline, type OutlineEntry, type OutlineFormat, type OutlineTopic, PARQUET_EXPORT_VERSION, PARQUET_REPORT_PATH, type ParquetExportFile, type ParquetExportOptions, type ParquetExportProgress, type ParquetExportReport, type ParquetExportSource, type ParquetTable, type PipelineFn, type ProfileEmbedder, RERANK_CANDIDATES_MAX, RERANK_CANDIDATES_MIN, RERANK_FINAL_K, ROUTE_SHARDS_EXPLICIT, ROUTE_SHARDS_PROACTIVE, SHARD_MAX_CHUNKS, SHARD_TARGET_CHUNKS, type ShardBitIndex, TRANSFORMERS_PEER_RANGE, type TableOfContentsFormat, type TableOfContentsOptions, type TokenChunkerOptions, type TokenizerFn, type TopicOverride, type TransformersModelOptions, type TransformersModule, type ValidateCatalogOptions, type VerifiedArtifacts, assertDuckdbCli, assetReferences, assignOutlineOrders, asymmetricTopK, chunkMarkdownProfile, compareCatalogVersions, compileKnowledgeCatalog, createProfileEmbedder, detectTableOfContents, duckdbVersion, exportCatalogParquet, extractGezkVerified, fetchKnowledgeRegistry, findDuckdbBinary, findRegistryEntry, hammingTopK, inspectGezkArchive, knowledgeEmbeddingProfile, loadMarkdownCatalog, newOutlineTopic, newerRegistryEntries, openCatalogDatabase, parquetKvMetadata, parseGitbookSummary, parseJupyterBookToc, parseMkdocsNav, readGezkManifest, readMkdocsDocsDir, rerankK, resolveOutlinePath, resolveTransformersModelOptions, runDuckdbScript, titleFromFolderName, transformersCachePath, transformersGraphOptions, validateExtractedCatalog, verifyProfileArtifacts, writeGezkArchive };
1421
+ export { type ArchiveEntry, type ArtifactCheck, type ArtifactRole, type AsymmetricHit, BGE_SMALL_EN_V15_1, BUILTIN_KNOWLEDGE_TRUST_ANCHORS, CENTROID_CHUNKS_PER, CENTROID_KMEANS_MAX_ITER, CENTROID_MAX_PER_SHARD, CENTROID_SAMPLE_MAX, type CatalogAssetInfo, type CatalogAssetRead, type CatalogCheck, type CatalogChunkHit, type CatalogDb, type CatalogDocumentMeta, CatalogHandle, CatalogOpenError, type CatalogTopic, type CatalogValidationReport, type CharChunkerOptions, type ChunkerOptions, type CompileAsset, type CompileKnowledgeCatalogOptions, type CompileReport, type CompileTopic, type DocumentLocationRow, type DuckdbCli, DuckdbError, EmbedderArtifactError, EmbedderUnavailableError, type FetchKnowledgeRegistryOptions, GEZEL_BGE_SMALL_EN_V15_1, GEZEL_MARKDOWN_CHUNKS_2, GEZEL_MULTILINGUAL_E5_SMALL_1, GEZK_ARCHIVE_LIMITS, GezkArchiveError, type GezkArchiveInspection, type HammingHit, KNOWLEDGE_EMBEDDING_PROFILES, KNOWLEDGE_TOOLCHAIN, type KnowledgeRegistryFetchCode, KnowledgeRegistryFetchError, type LoadMarkdownCatalogOptions, MARKDOWN_CHUNKS_2, MULTILINGUAL_E5_SMALL_1, MULTILINGUAL_E5_SMALL_2, type MarkdownCatalogSource, type MarkdownChunk, type ModelDownloadProgress, type Outline, type OutlineEntry, type OutlineFormat, type OutlineTopic, PARQUET_EXPORT_VERSION, PARQUET_REPORT_PATH, type ParquetExportFile, type ParquetExportOptions, type ParquetExportProgress, type ParquetExportReport, type ParquetExportSource, type ParquetTable, type PipelineFn, type ProfileEmbedder, QUERY_STOP_WORDS, RERANK_CANDIDATES_MAX, RERANK_CANDIDATES_MIN, RERANK_FINAL_K, ROUTE_SHARDS_EXPLICIT, ROUTE_SHARDS_PROACTIVE, SHARD_MAX_CHUNKS, SHARD_TARGET_CHUNKS, type ShardBitIndex, type SpatialMatch, TITLE_ROUTE_SHARDS, TRANSFORMERS_PEER_RANGE, type TableOfContentsFormat, type TableOfContentsOptions, type TokenChunkerOptions, type TokenizerFn, type TopicOverride, type TransformersModelOptions, type TransformersModule, type ValidateCatalogOptions, type VerifiedArtifacts, assertDuckdbCli, assetReferences, assignOutlineOrders, asymmetricTopK, chunkMarkdownProfile, compareCatalogVersions, compileKnowledgeCatalog, createProfileEmbedder, detectTableOfContents, duckdbVersion, exportCatalogParquet, extractGezkVerified, fetchKnowledgeRegistry, findDuckdbBinary, findRegistryEntry, hammingTopK, inspectGezkArchive, knowledgeEmbeddingProfile, loadMarkdownCatalog, newOutlineTopic, newerRegistryEntries, openCatalogDatabase, parquetKvMetadata, parseGitbookSummary, parseJupyterBookToc, parseMkdocsNav, readGezkManifest, readMkdocsDocsDir, rerankK, resolveOutlinePath, resolveTransformersModelOptions, runDuckdbScript, titleFromFolderName, transformersCachePath, transformersGraphOptions, validateExtractedCatalog, verifyProfileArtifacts, writeGezkArchive };