@g3nomaly/analyze 0.1.0 → 0.1.1

package/dist/embeddings/index-builder.d.ts

@@ -1,9 +1,11 @@
 import { type GraphNode, type SemanticIndex } from '../model';
 import type { EmbeddingModel, EmbeddingTable } from './model';
 /**
- * Embeds every searchable node of a scan and packs the result, with the model
+ * @brief Embeds every searchable node of a scan and packs the result, with the model
  * itself, into the form a reader loads.
  *
+ * @param nodes - Every node of the scan. A node with no searchable text gets no vector.
+ * @param model - Model that embeds the texts.
  * @param table - The data of the same model. It travels with the bundle, so a reader can embed a query.
  * @returns The index for `DocsBundle.semantic`.
  */

package/dist/embeddings/model.d.ts

@@ -1,24 +1,33 @@
-/** An embedding model as data: one vector per word. */
+/**
+ * An embedding model as data: one vector per word.
+ *
+ * @property name - Name of the model, for display.
+ * @property dimensions - Length of every vector.
+ * @property vocabulary - The words of the model. The index of a word is its row in `vectors`.
+ * @property vectors - One row of `dimensions` small whole numbers per word. The shipped model uses -7 to 7.
+ */
 export interface EmbeddingTable {
-    /** Name of the model, for display. */
     readonly name: string;
-    /** Length of every vector. */
     readonly dimensions: number;
-    /** The words of the model. The index of a word is its row in `vectors`. */
     readonly vocabulary: readonly string[];
-    /** One row of `dimensions` small whole numbers per word. The shipped model uses -7 to 7. */
     readonly vectors: Int8Array;
 }
-/** One part of a text and how much it counts. */
+/**
+ * One part of a text and how much it counts.
+ *
+ * @property text - The part, as plain text.
+ * @property weight - How much the part counts against the other parts.
+ */
 export interface WeightedText {
     readonly text: string;
     readonly weight: number;
 }
 /**
- * Turns text into an embedding with a table of word vectors. The vector of a
- * word was computed in advance by a contextual model that read the word on
- * its own. The vector of a text is the mean of the vectors of its words.
- * There is no neural network to run, so it works on any CPU and in a browser.
+ * @brief Turns text into an embedding with a table of word vectors.
+ *
+ * The vector of a word was computed in advance by a contextual model that read the word on
+ * its own. The vector of a text is the mean of the vectors of its words. No neural network runs
+ * at embedding time: a text is only a sum of table rows.
  *
  * Holds the table's vectors and a `WordVocabulary` over its words.
  * `api/embedding.ts` creates one from the shipped table and passes it to
@@ -26,6 +35,8 @@ export interface WeightedText {
  * `SemanticSearcher` creates one from the table stored in a bundle to embed
  * what a reader types.
  *
+ * @property medianLength - Median length of a row of the table, computed on first use.
+ *
  * @example
  * const model = new EmbeddingModel({
  *   name: index.model,
@@ -39,11 +50,11 @@ export declare class EmbeddingModel {
     readonly dimensions: number;
     private readonly vectors;
     private readonly vocabulary;
-    /** Median length of a row of the table. Computed on first use. */
     private medianLength;
     /**
      * Creates a model from its table.
      *
+     * @param table - The vectors and the words they belong to.
      * @throws {Error} When the table does not hold one row per word.
      */
     constructor(table: EmbeddingTable);
@@ -58,6 +69,7 @@ export declare class EmbeddingModel {
      * long description. Each part is embedded on its own, so a short part is
      * not drowned out by a long one.
      *
+     * @param parts - The parts of the text, each with its weight.
      * @returns A vector of length 1, or `null` when the model knows no word of any part.
      */
     embedParts(parts: readonly WeightedText[]): Float32Array | null;
@@ -78,8 +90,7 @@ export declare class EmbeddingModel {
      */
     wordVector(word: string): Float32Array | null;
     /**
-     * Says how much a word counts in a query. The table gives a word that says
-     * a lot a long row, so the length of the row is the weight.
+     * Weighs a word of a query by the length of its row in the table.
      *
      * @param word - A word from `contentWords`.
      * @returns The length of the word's row, or the median length for a word the model does not have.
@@ -95,12 +106,14 @@ export declare class EmbeddingModel {
     /**
      * Reads one row of the table.
      *
+     * @param row - Index of the row.
      * @returns The values of the row. A view, not a copy.
      */
     private row;
     /**
      * Measures one row of the table.
      *
+     * @param row - Index of the row.
      * @returns The Euclidean length of the row.
      */
     private lengthOf;

package/dist/embeddings/searcher.d.ts

@@ -1,12 +1,16 @@
 import type { NodeRef, SemanticIndex } from '../model';
-/** A node and how close its meaning is to the query. */
+/**
+ * A node and how close its meaning is to the query.
+ *
+ * @property node - The node the hit is about.
+ * @property score - From 0 to 1: 1 is the same meaning, 0 is unrelated.
+ */
 export interface SemanticHit {
     readonly node: NodeRef;
-    /** From 0 to 1: 1 is the same meaning, 0 is unrelated. */
     readonly score: number;
 }
 /**
- * Finds nodes by meaning in the index of a bundle.
+ * @brief Finds nodes by meaning in the index of a bundle.
  *
  * Holds the node vectors and word lists of a `SemanticIndex`, and decodes the
  * `EmbeddingModel` stored in it on the first query. `searcherOf` in
@@ -14,6 +18,13 @@ export interface SemanticHit {
  * for the page and the CLI alike; `scripts/search-benchmark.ts` creates one
  * too. `search` scores every node against a query. `similarTo` compares one
  * node with the others.
+ *
+ * @property model - The model, decoded on the first query. The model is a few megabytes of text.
+ * @property wordVectors - The vector of each word of the index, `null` for a word the model does not have. Filled on the first query.
+ *
+ * @example
+ * const searcher = new SemanticSearcher(graph.semantic);
+ * searcher.search('ship', 6, 0.5);
  */
 export declare class SemanticSearcher {
     private readonly index;
@@ -24,14 +35,16 @@ export declare class SemanticSearcher {
     private readonly rows;
     private readonly words;
     private readonly wordIds;
-    /** Decoded on the first query. The model is a few megabytes of text. */
     private model;
-    /** The vector of each word of the index, `null` for a word the model does not have. Filled on the first query. */
     private wordVectors;
-    /** Creates a searcher for one index. */
+    /**
+     * Creates a searcher for one index.
+     *
+     * @param index - The index of a bundle, as `DocsBundle.semantic` holds it.
+     */
     constructor(index: SemanticIndex);
     /**
-     * Finds the nodes whose meaning is closest to a query.
+     * @brief Finds the nodes whose meaning is closest to a query.
      *
      * The score of a node has two parts. One compares the query as a whole
      * with the name and the text of the node as a whole. The other takes each
@@ -40,6 +53,7 @@ export declare class SemanticSearcher {
      * in the model. A one-word query is scored mostly by the second part.
      *
      * @param query - What the reader typed.
+     * @param limit - Most hits returned.
      * @param minScore - Hits below this score are left out.
      * @returns The hits, best first.
      */
@@ -47,6 +61,8 @@ export declare class SemanticSearcher {
     /**
      * Finds the nodes whose meaning is closest to that of a node.
      *
+     * @param node - The node to compare the others with.
+     * @param limit - Most hits returned.
      * @param minScore - Hits below this score are left out.
      * @returns The hits, best first, without the node itself. Empty when the node has no vector.
      */
@@ -60,6 +76,7 @@ export declare class SemanticSearcher {
     /**
      * Compares each word of a query with every word of the index.
      *
+     * @param model - The model that embeds the words.
      * @param query - What the reader typed.
      * @returns One entry per word of the query that carries meaning.
      */

package/dist/embeddings/vectors.d.ts

@@ -30,7 +30,7 @@ export declare function similarity(query: Float32Array, rows: Int8Array, row: nu
  */
 export declare function rowOf(rows: Int8Array, row: number, dimensions: number): Float32Array | null;
 /**
- * Stores small whole numbers in four bits each, two per byte. Halves the
+ * @brief Stores small whole numbers in four bits each, two per byte. Halves the
  * size of the model table.
  *
  * @param values - Numbers from -8 to 7.
@@ -41,6 +41,7 @@ export declare function packNibbles(values: Int8Array): Uint8Array;
 /**
  * Reads back numbers that `packNibbles` stored.
  *
+ * @param packed - Bytes that `packNibbles` wrote.
  * @param count - How many numbers to read.
  * @returns The numbers, from -8 to 7.
  */
@@ -48,6 +49,7 @@ export declare function unpackNibbles(packed: Uint8Array, count: number): Int8Ar
 /**
  * Encodes bytes as base64 text, for JSON.
  *
+ * @param bytes - The bytes to encode.
  * @returns Base64 text.
  */
 export declare function toBase64(bytes: Int8Array | Uint8Array): string;

package/dist/embeddings/words.d.ts

@@ -1,5 +1,5 @@
 /**
- * Splits a text into lowercase words and single punctuation marks. Identifiers
+ * @brief Splits a text into lowercase words and single punctuation marks. Identifiers
  * are split into their words, accents are dropped, and a short form from code
  * is replaced with the word it stands for, so `srcDir` reads `source`, `directory`.
  *
@@ -15,12 +15,16 @@ export declare function wordsOf(text: string): string[];
  */
 export declare function isPunctuation(word: string): boolean;
 /**
- * The words an embedding model has a vector for.
+ * @brief The words an embedding model has a vector for.
  *
  * Holds a map from each word to its row in the model table. `EmbeddingModel`
  * creates one from its table and uses it to find the row of a word. The
  * scanner side and the page look words up the same way, so a query meets the
  * vectors it was meant for.
+ *
+ * @example
+ * const vocabulary = new WordVocabulary(['cat', 'dog']);
+ * vocabulary.rowOf('dogs'); // 1, through the stem `dog`
  */
 export declare class WordVocabulary {
     private readonly rows;
@@ -31,7 +35,7 @@ export declare class WordVocabulary {
      */
     constructor(words: readonly string[]);
     /**
-     * Finds the row that carries the meaning of a word: that of the word
+     * @brief Finds the row that carries the meaning of a word: that of the word
      * itself, else that of its stem when the word is a stem with a plain
      * ending, as `sailings` is of `sailing`.
      *

package/dist/index.d.ts

@@ -5,5 +5,5 @@ export type { WarningHandler } from './api/options';
 export { type RefsOptions, type RefsResult, refs } from './api/refs';
 export { type SearchOptions, type SearchResult, search } from './api/search';
 export { type ShowOptions, show } from './api/show';
-export type { EdgeKind, NodeKind, Section } from './model';
+export type { EdgeKind, NodeKind, NodeType, Section } from './model';
 export type { ContentReport, DatabaseObjectReport, DeclarationReport, NodeReport, NodeSummary, Reference, References, SearchHit, SearchMode, TaskReport, } from './retrieval';