@elizaos/core 2.0.0-alpha.52 → 2.0.0-alpha.53

package/dist/schemas/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Abstract database schemas — the canonical data model for elizaOS.
+ *
+ * These SchemaTable objects define the structure of all core tables in a
+ * database-agnostic format. Use buildBaseTables(adapter) to convert them
+ * into concrete Drizzle table objects for a specific dialect.
+ *
+ * This module also exports advanced memory schemas (longTermMemories,
+ * sessionSummaries, memoryAccessLogs) which are part of the enhanced
+ * memory subsystem.
+ */
+import { longTermMemories, memoryAccessLogs, sessionSummaries } from "../advanced-memory/schemas/index.ts";
+import type { BuildTableFn, DialectAdapter } from "../types/schema-builder.ts";
+import { agentSchema } from "./agent.ts";
+import { cacheSchema } from "./cache.ts";
+import { channelSchema } from "./channel.ts";
+import { channelParticipantSchema } from "./channel-participant.ts";
+import { componentSchema } from "./component.ts";
+import { embeddingSchema } from "./embedding.ts";
+import { entitySchema } from "./entity.ts";
+import { logSchema } from "./log.ts";
+import { memorySchema } from "./memory.ts";
+import { messageSchema } from "./message.ts";
+import { messageServerSchema } from "./message-server.ts";
+import { messageServerAgentSchema } from "./message-server-agent.ts";
+import { pairingAllowlistSchema } from "./pairing-allowlist.ts";
+import { pairingRequestSchema } from "./pairing-request.ts";
+import { participantSchema } from "./participant.ts";
+import { relationshipSchema } from "./relationship.ts";
+import { roomSchema } from "./room.ts";
+import { serverSchema } from "./server.ts";
+import { taskSchema } from "./task.ts";
+import { worldSchema } from "./world.ts";
+export { agentSchema, cacheSchema, channelParticipantSchema, channelSchema, componentSchema, embeddingSchema, entitySchema, logSchema, longTermMemories, memoryAccessLogs, memorySchema, messageSchema, messageServerAgentSchema, messageServerSchema, pairingAllowlistSchema, pairingRequestSchema, participantSchema, relationshipSchema, roomSchema, serverSchema, sessionSummaries, taskSchema, worldSchema, };
+/**
+ * Type for the object returned by buildBaseTables().
+ * Represents all 20 core database tables as ORM table objects.
+ */
+export interface BaseTables {
+    agent: unknown;
+    cache: unknown;
+    channel: unknown;
+    channelParticipant: unknown;
+    component: unknown;
+    embedding: unknown;
+    entity: unknown;
+    log: unknown;
+    memory: unknown;
+    message: unknown;
+    messageServer: unknown;
+    messageServerAgent: unknown;
+    pairingAllowlist: unknown;
+    pairingRequest: unknown;
+    participant: unknown;
+    relationship: unknown;
+    room: unknown;
+    server: unknown;
+    task: unknown;
+    world: unknown;
+}
+/**
+ * Factory: build all 20 base tables using the given dialect adapter and buildTable function.
+ *
+ * This is the single source of truth for the elizaOS data model. Plugins
+ * import this function and pass their dialect adapter (pgAdapter, mysqlAdapter)
+ * to get concrete ORM table objects.
+ *
+ * The buildTable function is provided by the plugin (e.g., from plugin-sql).
+ *
+ * @param buildTable - The buildTable function from the plugin
+ * @param adapter - The dialect-specific adapter (pgAdapter or mysqlAdapter).
+ * @returns An object with all 20 tables, keyed by camelCase name.
+ */
+export declare function buildBaseTables(buildTable: BuildTableFn, adapter: DialectAdapter): BaseTables;
+//# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACN,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EACN,WAAW,EACX,WAAW,EACX,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,EACZ,SAAS,EAET,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,GACX,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,UAAU,EAAE,YAAY,EACxB,OAAO,EAAE,cAAc,GACrB,UAAU,CAuBZ"}

package/dist/schemas/log.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the logs table.
+ */
+export declare const logSchema: SchemaTable;
+//# sourceMappingURL=log.d.ts.map

package/dist/schemas/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/schemas/log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,WAyFvB,CAAC"}

package/dist/schemas/memory.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the memories table.
+ * Has expression-based indexes on JSON fields and check constraints for metadata validation.
+ */
+export declare const memorySchema: SchemaTable;
+//# sourceMappingURL=memory.d.ts.map

package/dist/schemas/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/schemas/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WAkK1B,CAAC"}

package/dist/schemas/message-server-agent.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the message_server_agents table.
+ * Junction table with composite primary key.
+ */
+export declare const messageServerAgentSchema: SchemaTable;
+//# sourceMappingURL=message-server-agent.d.ts.map

package/dist/schemas/message-server-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-server-agent.d.ts","sourceRoot":"","sources":["../../src/schemas/message-server-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAqDtC,CAAC"}

package/dist/schemas/message-server.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the message_servers table.
+ */
+export declare const messageServerSchema: SchemaTable;
+//# sourceMappingURL=message-server.d.ts.map

package/dist/schemas/message-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-server.d.ts","sourceRoot":"","sources":["../../src/schemas/message-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,WA0DjC,CAAC"}

package/dist/schemas/message.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the central_messages table.
+ * Has a self-referencing foreign key (in_reply_to_root_message_id).
+ */
+export declare const messageSchema: SchemaTable;
+//# sourceMappingURL=message.d.ts.map

package/dist/schemas/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/schemas/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,WAqG3B,CAAC"}

package/dist/schemas/pairing-allowlist.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the pairing_allowlist table.
+ * Has multiple indexes including a unique constraint.
+ */
+export declare const pairingAllowlistSchema: SchemaTable;
+//# sourceMappingURL=pairing-allowlist.d.ts.map

package/dist/schemas/pairing-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-allowlist.d.ts","sourceRoot":"","sources":["../../src/schemas/pairing-allowlist.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAuEpC,CAAC"}

package/dist/schemas/pairing-request.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the pairing_requests table.
+ * Has multiple unique indexes.
+ */
+export declare const pairingRequestSchema: SchemaTable;
+//# sourceMappingURL=pairing-request.d.ts.map

package/dist/schemas/pairing-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-request.d.ts","sourceRoot":"","sources":["../../src/schemas/pairing-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WA2FlC,CAAC"}

package/dist/schemas/participant.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the participants table.
+ */
+export declare const participantSchema: SchemaTable;
+//# sourceMappingURL=participant.d.ts.map

package/dist/schemas/participant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../src/schemas/participant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAuF/B,CAAC"}

package/dist/schemas/relationship.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the relationships table.
+ * Has unique constraint on (source_entity_id, target_entity_id, agent_id).
+ */
+export declare const relationshipSchema: SchemaTable;
+//# sourceMappingURL=relationship.d.ts.map

package/dist/schemas/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../../src/schemas/relationship.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAiGhC,CAAC"}

package/dist/schemas/room.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the rooms table.
+ */
+export declare const roomSchema: SchemaTable;
+//# sourceMappingURL=room.d.ts.map

package/dist/schemas/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../src/schemas/room.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,WAkFxB,CAAC"}

package/dist/schemas/server.d.ts

@@ -0,0 +1,7 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the servers table.
+ * Used for RLS multi-tenant isolation in multi-server deployments.
+ */
+export declare const serverSchema: SchemaTable;
+//# sourceMappingURL=server.d.ts.map

package/dist/schemas/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/schemas/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WA4B1B,CAAC"}

package/dist/schemas/task.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the tasks table.
+ */
+export declare const taskSchema: SchemaTable;
+//# sourceMappingURL=task.d.ts.map

package/dist/schemas/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/schemas/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,WA2FxB,CAAC"}

package/dist/schemas/world.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaTable } from "../types/schema.ts";
+/**
+ * Abstract schema for the worlds table.
+ */
+export declare const worldSchema: SchemaTable;
+//# sourceMappingURL=world.d.ts.map

package/dist/schemas/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/schemas/world.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WA4DzB,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,381 @@
+/**
+ * Interface for tokenization statistics.
+ */
+interface TokenizationStats {
+    /** Number of words in the original text before any processing. */
+    originalWordCount: number;
+    /** Number of words removed because they were identified as stop words. */
+    stopWordsRemoved: number;
+    /** Number of words that were stemmed (only if stemming is enabled). */
+    stemmedWords: number;
+    /** Time taken for tokenization in milliseconds. */
+    processingTimeMs: number;
+}
+/**
+ * Interface for the result of tokenization.
+ */
+interface TokenizationResult {
+    /** Array of processed tokens (words). */
+    tokens: string[];
+    /** Optional statistics about the tokenization process. */
+    stats?: TokenizationStats;
+}
+/**
+ * Interface for stemming rules.
+ */
+interface StemmingRule {
+    /** A RegExp pattern or string to match suffixes. */
+    pattern: RegExp | string;
+    /** The replacement string or function. */
+    replacement: string | ((substring: string, ...args: unknown[]) => string);
+    /** Optional minimum measure (complexity) of the word stem for the rule to apply. */
+    minMeasure?: number;
+}
+/**
+ * Options for configuring the Tokenizer.
+ */
+export interface TokenizerOptions {
+    /** A set of words to be ignored during tokenization. Defaults to an empty set. */
+    stopWords?: Set<string>;
+    /** The minimum length for a token to be kept. Defaults to 2. Numeric tokens are always kept. */
+    minLength?: number;
+    /** Whether to apply stemming to tokens. Defaults to false. */
+    stemming?: boolean;
+    /** Custom stemming rules to apply before the default Porter2 stemmer. Defaults to an empty array. */
+    stemmingRules?: StemmingRule[];
+}
+/**
+ * Flexible text tokenizer with support for stop words, minimum token length,
+ * Unicode normalization, and optional Porter2 stemming with custom rules.
+ */
+export declare class Tokenizer {
+    /** Set of stop words to ignore. */
+    readonly stopWords: Set<string>;
+    /** Minimum length of tokens to keep. */
+    readonly minLength: number;
+    /** Flag indicating if stemming is enabled. */
+    readonly stemming: boolean;
+    /** Custom stemming rules. */
+    readonly stemmingRules: {
+        pattern: RegExp;
+        replacement: string | ((substring: string, ...args: unknown[]) => string);
+        minMeasure?: number;
+    }[];
+    /** Default options for the Tokenizer. */
+    static readonly DEFAULT_OPTIONS: Required<TokenizerOptions>;
+    /**
+     * Creates a new tokenizer instance.
+     * @param options - Tokenization options including stop words, min length, stemming, and custom rules.
+     */
+    constructor(options?: TokenizerOptions);
+    /**
+     * Tokenizes input text into an array of processed terms.
+     * Steps:
+     * 1. Cleans the text (lowercase, normalize, remove punctuation/symbols).
+     * 2. Splits the text into potential tokens.
+     * 3. Filters tokens based on `minLength` and `stopWords`.
+     * 4. Applies stemming if `stemming` is true (custom rules first, then Porter2).
+     * 5. Optionally calculates statistics.
+     *
+     * @param text - The input text string to tokenize.
+     * @param includeStats - If true, returns tokenization statistics along with tokens. Defaults to false.
+     * @returns A `TokenizationResult` object containing the array of tokens and optional stats.
+     * @throws {Error} If the input text is null, undefined, or empty.
+     */
+    tokenize(text: string, includeStats?: boolean): TokenizationResult;
+    /**
+     * Cleans and normalizes text for tokenization.
+     * - Converts to lowercase.
+     * - Normalizes Unicode characters (NFKD).
+     * - Removes control characters and zero-width spaces.
+     * - Removes diacritical marks (accents).
+     * - Removes emojis and pictographs.
+     * - Removes common symbols (™, ®, ©, ℠, ‼).
+     * - Replaces Unicode punctuation with spaces.
+     * - Removes characters not matching basic Latin, CJK, Hangul, or whitespace.
+     * - Collapses multiple spaces into single spaces.
+     * - Trims leading/trailing whitespace.
+     *
+     * @param text - Input text to clean.
+     * @returns Cleaned and normalized text, ready for splitting into tokens.
+     *
+     * @example
+     * cleanText("Hello, World™!") // "hello world"
+     * cleanText("héllo 👋") // "hello"
+     * cleanText("Hello 世界!") // "hello 世界"
+     * cleanText("I'm don't") // "i'm don't" (apostrophes kept by replacing punctuation with space)
+     * cleanText("test©2023") // "test 2023"
+     */
+    cleanText(text: string): string;
+    /**
+     * Checks if a token is valid (meets `minLength` criteria and is not a stop word).
+     * Numeric tokens are always considered valid regardless of length.
+     * @param token - The token string to validate.
+     * @returns `true` if the token is valid, `false` otherwise.
+     */
+    isValidToken(token: string): boolean;
+    /**
+     * Applies stemming to a single word.
+     * First, tries to apply custom stemming rules defined in `stemmingRules`.
+     * If no custom rule matches, applies the default Porter2 stemming algorithm.
+     * Words shorter than 3 characters are not stemmed.
+     * @param word - The word to stem.
+     * @returns The stemmed word.
+     */
+    stemWord(word: string): string;
+    /**
+     * Checks if the character at a given index in a word is a consonant.
+     * Treats 'y' as a consonant if it's the first letter or follows a consonant.
+     * @param word - The word string.
+     * @param i - The index of the character to check.
+     * @returns `true` if the character is a consonant, `false` otherwise.
+     */
+    isConsonant(word: string, i: number): boolean;
+    /**
+     * Calculates the "measure" of a word stem (approximates syllable count).
+     * The measure (m) is the number of times a sequence of vowels is followed by a
+     * sequence of consonants (VC). Used in some stemming rules.
+     * Example: measure("tree") = 0, measure("trouble") = 1, measure("private") = 2
+     * @param word - The word (or stem) to measure.
+     * @returns The measure (m) of the word.
+     */
+    measure(word: string): number;
+}
+/**
+ * BM25 Options Interface.
+ * Extends TokenizerOptions and adds BM25 specific parameters.
+ */
+interface BM25Options extends TokenizerOptions {
+    /**
+     * Term frequency saturation parameter (k1). Controls how quickly term frequency
+     * saturates. Higher values mean TF contributes more significantly even for high counts.
+     * Typical values are between 1.2 and 2.0. Default: 1.2.
+     */
+    k1?: number;
+    /**
+     * Document length normalization parameter (b). Controls the influence of document
+     * length. 0 means no length normalization, 1 means full normalization.
+     * Typical values are around 0.75. Default: 0.75.
+     */
+    b?: number;
+    /**
+     * A dictionary defining boost factors for specific document fields.
+     * Terms found in fields with higher boost factors will contribute more to the score.
+     * Example: `{ title: 2, body: 1 }`. Default: `{}` (no boosts).
+     */
+    fieldBoosts?: {
+        [key: string]: number;
+    };
+}
+/**
+ * Represents a search result item.
+ */
+interface SearchResult {
+    /** The index of the matching document in the original document array. */
+    index: number;
+    /** The BM25 relevance score for the document. Higher scores indicate better relevance. */
+    score: number;
+    /** The actual document object (optional, depends on how results are retrieved). */
+    doc?: Record<string, unknown>;
+}
+/**
+ * Implements the Okapi BM25 (Best Matching 25) ranking function for information retrieval.
+ *
+ * BM25 ranks documents based on the query terms appearing in each document,
+ * considering term frequency (TF) and inverse document frequency (IDF).
+ * It improves upon basic TF-IDF by incorporating:
+ * - Term Frequency Saturation (k1): Prevents overly frequent terms from dominating the score.
+ * - Document Length Normalization (b): Penalizes documents that are longer than average,
+ *   assuming longer documents are more likely to contain query terms by chance.
+ *
+ * Key Components:
+ * - Tokenizer: Processes text into terms (words), handles stop words and stemming.
+ * - Document Indexing: Stores document lengths, term frequencies per document,
+ *   and overall document frequency for each term.
+ * - IDF Calculation: Measures the informativeness of a term based on how many documents contain it.
+ * - Scoring: Combines TF, IDF, document length, and parameters k1/b to calculate relevance.
+ */
+export declare class BM25 {
+    /** Term frequency saturation parameter (k1). */
+    readonly termFrequencySaturation: number;
+    /** Document length normalization factor (b). */
+    readonly lengthNormalizationFactor: number;
+    /** Tokenizer instance used for processing text. */
+    readonly tokenizer: Tokenizer;
+    /** Array storing the length (number of tokens, adjusted by field boosts) of each document. */
+    documentLengths: Uint32Array;
+    /** Average length of all documents in the index. */
+    averageDocLength: number;
+    /** Map from term (string) to its unique integer index. */
+    termToIndex: Map<string, number>;
+    /** Array storing the document frequency (number of docs containing the term) for each term index. */
+    documentFrequency: Uint32Array;
+    /** Map from term index to another map storing `docIndex: termFrequencyInDoc`. */
+    termFrequencies: Map<number, Map<number, number>>;
+    /** Boost factors for different fields within documents. */
+    readonly fieldBoosts: {
+        [key: string]: number;
+    };
+    /** Array storing the original documents added to the index. */
+    documents: Array<Record<string, unknown>>;
+    /**
+     * Creates a new BM25 search instance.
+     * @param docs - Optional array of initial documents (objects with string fields) to index.
+     * @param options - Configuration options for BM25 parameters (k1, b), tokenizer (stopWords, stemming, minLength), and field boosts.
+     */
+    constructor(docs?: Array<Record<string, unknown>>, options?: BM25Options);
+    /**
+     * Processes an array of documents to build the initial index structures.
+     * Calculates document lengths, term frequencies, document frequencies, and average document length.
+     * @param docs - Array of documents to process.
+     * @returns An object containing the calculated index data.
+     * @internal
+     */
+    private processDocuments;
+    /**
+     * Recalculates the average document length based on the current `documentLengths`.
+     * @internal
+     */
+    private recalculateAverageLength;
+    /**
+     * Searches the indexed documents for a given query string using the BM25 ranking formula.
+     *
+     * @param query - The search query text.
+     * @param topK - The maximum number of top-scoring results to return. Defaults to 10.
+     * @returns An array of `SearchResult` objects, sorted by descending BM25 score.
+     */
+    search(query: string, topK?: number): SearchResult[];
+    /**
+     * Searches for an exact phrase within the indexed documents.
+     * Ranks documents containing the exact sequence of tokens higher.
+     * Basic implementation - proximity-based phrase search could improve results.
+     *
+     * @param phrase - The exact phrase to search for.
+     * @param topK - The maximum number of results to return. Defaults to 10.
+     * @returns An array of `SearchResult` objects, sorted by score, for documents containing the phrase.
+     */
+    searchPhrase(phrase: string, topK?: number): SearchResult[];
+    /**
+     * Calculates a BM25-like score for a sequence of phrase tokens within a specific document.
+     * Sums the individual BM25 scores of the terms in the phrase for that document.
+     * @param phraseTokens - The tokenized phrase.
+     * @param docIndex - The index of the document to score against.
+     * @returns The calculated phrase score for the document.
+     * @internal
+     */
+    private calculatePhraseScore;
+    /**
+     * Adds a single new document to the index.
+     * Updates all internal index structures incrementally.
+     * For bulk additions, prefer `addDocumentsParallel` for better performance.
+     *
+     * @param doc - The document object (with string fields) to add.
+     * @throws {Error} If the document is null or undefined.
+     */
+    addDocument(doc: Record<string, unknown>): Promise<void>;
+    /**
+     * Calculates the Inverse Document Frequency (IDF) for a given term index.
+     * Uses the BM25 IDF formula: log(1 + (N - n + 0.5) / (n + 0.5))
+     * where N is the total number of documents and n is the number of documents
+     * containing the term. The +1 smooths the logarithm.
+     *
+     * @param termIndex - The integer index of the term.
+     * @returns The IDF score for the term. Returns 0 if the term is not found or has 0 DF.
+     */
+    calculateIdf(termIndex: number): number;
+    /**
+     * Retrieves the term frequency (TF) for a specific term in a specific document.
+     * @param termIndex - The integer index of the term.
+     * @param docIndex - The index of the document.
+     * @returns The term frequency, or 0 if the term is not in the document or indices are invalid.
+     */
+    getTermFrequency(termIndex: number, docIndex: number): number;
+    /**
+     * Retrieves the original document object stored at a given index.
+     * @param index - The index of the document to retrieve.
+     * @returns The document object.
+     * @throws {Error} If the index is out of bounds.
+     */
+    getDocument(index: number): Record<string, unknown>;
+    /**
+     * Clears all indexed documents and resets the BM25 instance to its initial state.
+     */
+    clearDocuments(): void;
+    /**
+     * Gets the total number of documents currently indexed.
+     * @returns The document count.
+     */
+    getDocumentCount(): number;
+    /**
+     * Adds multiple documents sequentially by calling `addDocument` for each.
+     * This method processes documents sequentially in the main thread.
+     * @param docs - An array of documents to add.
+     */
+    addDocuments(docs: Array<Record<string, unknown>>): Promise<void>;
+}
+/** Source identifier for hybrid search results */
+export type HybridSource = string;
+/** Result from vector similarity search */
+export type HybridVectorResult = {
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    source: HybridSource;
+    snippet: string;
+    vectorScore: number;
+};
+/** Result from keyword (BM25) search */
+export type HybridKeywordResult = {
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    source: HybridSource;
+    snippet: string;
+    textScore: number;
+};
+/**
+ * Build an FTS (Full-Text Search) query from a raw search string.
+ * Extracts alphanumeric tokens and joins them with AND for strict matching.
+ *
+ * @param raw - The raw search query string.
+ * @returns The FTS query string, or null if no valid tokens found.
+ */
+export declare function buildFtsQuery(raw: string): string | null;
+/**
+ * Convert BM25 rank to a normalized score between 0 and 1.
+ * Lower rank = higher score.
+ *
+ * @param rank - The BM25 rank value.
+ * @returns A normalized score where 1 is best and 0 is worst.
+ */
+export declare function bm25RankToScore(rank: number): number;
+/**
+ * Merge vector similarity and keyword search results using weighted scoring.
+ *
+ * This implements a hybrid search approach where results from both vector
+ * similarity search and keyword (BM25) search are combined. Results that
+ * appear in both searches get boosted scores.
+ *
+ * @param params.vector - Results from vector similarity search.
+ * @param params.keyword - Results from keyword (BM25) search.
+ * @param params.vectorWeight - Weight for vector similarity scores (default: 0.7).
+ * @param params.textWeight - Weight for keyword/text scores (default: 0.3).
+ * @returns Merged and sorted results with combined scores.
+ */
+export declare function mergeHybridResults(params: {
+    vector: HybridVectorResult[];
+    keyword: HybridKeywordResult[];
+    vectorWeight: number;
+    textWeight: number;
+}): Array<{
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    snippet: string;
+    source: HybridSource;
+}>;
+export {};
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/secrets.d.ts

@@ -0,0 +1,6 @@
+import type { Character } from "./types";
+export declare function hasCharacterSecrets(character: Character): boolean;
+export declare function setDefaultSecretsFromEnv(character: Character, options?: {
+    skipEnvMerge?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAIjE;AAoBD,wBAAsB,wBAAwB,CAC7C,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,OAAO,CAAC,CAYlB"}