latticesql 1.2.6 → 1.3.1

package/dist/index.d.ts

@@ -812,6 +812,90 @@ interface TableDefinition {
      * ```
      */
     relations?: Record<string, Relation>;
+    /**
+     * Enable semantic search for this table via embeddings.
+     *
+     * When configured, Lattice computes and stores vector embeddings for
+     * the specified text fields. Use `lattice.search(table, query, opts)`
+     * to retrieve rows by semantic similarity.
+     *
+     * The `embed` function is called to generate vectors — bring your own
+     * embedding model (OpenAI, local model, etc.).
+     *
+     * @example
+     * ```ts
+     * embeddings: {
+     *   fields: ['title', 'body'],
+     *   embed: async (text) => openai.embeddings.create({ input: text, model: 'text-embedding-3-small' }).then(r => r.data[0].embedding),
+     * }
+     * ```
+     */
+    embeddings?: EmbeddingsConfig;
+    /**
+     * Enable reward tracking for this table. When `true`, Lattice
+     * auto-adds `_reward_total REAL DEFAULT 0` and `_reward_count INTEGER
+     * DEFAULT 0` columns. Rows are sorted by `_reward_total DESC` before
+     * rendering (unless overridden by `prioritizeBy`).
+     *
+     * Use `lattice.reward(table, id, scores)` to update reward values.
+     */
+    rewardTracking?: boolean;
+    /**
+     * When `rewardTracking` is enabled, automatically soft-delete rows
+     * whose `_reward_total` falls below this threshold during rendering.
+     * Requires a `deleted_at` column on the table. Default: no pruning.
+     */
+    pruneBelow?: number;
+    /**
+     * Pipeline of enrichment functions applied to rows after query and
+     * filtering but before rendering. Each function receives the row
+     * array and returns a (possibly transformed) row array.
+     *
+     * Use enrichment hooks to cluster, annotate, summarize, or
+     * cross-reference rows without modifying the underlying data.
+     *
+     * @example
+     * ```ts
+     * enrich: [
+     *   (rows) => rows.map(r => ({ ...r, _age: Date.now() - new Date(r.created_at as string).getTime() })),
+     *   (rows) => rows.length > 50 ? [{ summary: `${rows.length} items` }] : rows,
+     * ]
+     * ```
+     */
+    enrich?: ((rows: Row[]) => Row[])[];
+    /**
+     * Dynamic filter that scores rows against the current task context
+     * (set via `lattice.setTaskContext()`). Called before `filter` and
+     * before rendering. Only rows for which the function returns `true`
+     * are included.
+     *
+     * The second argument is the current task-context string (empty string
+     * when none has been set).
+     *
+     * @example
+     * ```ts
+     * relevanceFilter: (row, ctx) =>
+     *   ctx ? String(row.body).toLowerCase().includes(ctx.toLowerCase()) : true
+     * ```
+     */
+    relevanceFilter?: (row: Row, taskContext: string) => boolean;
+    /**
+     * Maximum estimated token count for the rendered output.
+     * When the rendered content exceeds this budget, rows are pruned
+     * (lowest-priority first) and re-rendered with a truncation notice.
+     *
+     * Token count is estimated at ~4 characters per token.
+     */
+    tokenBudget?: number;
+    /**
+     * Controls row priority when `tokenBudget` forces pruning.
+     *
+     * - `string` — column name to sort by descending (highest value = highest priority).
+     * - `(a, b) => number` — custom comparator (positive = a has higher priority).
+     *
+     * When omitted, rows at the end of the query result are pruned first.
+     */
+    prioritizeBy?: string | ((a: Row, b: Row) => number);
 }
 interface MultiTableDefinition {
     /** Returns the "anchor" entities — one output file is produced per anchor */
@@ -823,6 +907,58 @@ interface MultiTableDefinition {
     /** Additional table names to query and pass into render */
     tables?: string[];
 }
+/**
+ * Configuration for embedding-based semantic search on a table.
+ */
+interface EmbeddingsConfig {
+    /** Column names whose values are concatenated and embedded. */
+    fields: string[];
+    /**
+     * Function that converts text into a numeric vector.
+     * Bring your own model — Lattice does not bundle an embedding provider.
+     */
+    embed: (text: string) => Promise<number[]>;
+}
+/**
+ * Options for `Lattice.search()`.
+ */
+interface SearchOptions {
+    /** Maximum number of results to return. Default: 10. */
+    topK?: number;
+    /**
+     * Minimum cosine similarity threshold (0–1). Results below this
+     * score are excluded. Default: 0.
+     */
+    minScore?: number;
+}
+/**
+ * A single search result returned by `Lattice.search()`.
+ */
+interface SearchResult {
+    /** The matched row from the source table. */
+    row: Row;
+    /** Cosine similarity score (0–1). */
+    score: number;
+}
+/**
+ * Dimension scores passed to `Lattice.reward()`.
+ * Values should be between 0 and 1. The total reward is the average
+ * of all provided dimension scores, accumulated over multiple calls.
+ */
+interface RewardScores {
+    [dimension: string]: number;
+}
+/**
+ * Result of a writeback validation check.
+ */
+interface WritebackValidationResult {
+    /** Whether the entry passed validation. */
+    pass: boolean;
+    /** Overall quality score (0–1). */
+    score: number;
+    /** Human-readable reason when validation fails. */
+    reason?: string;
+}
 interface WritebackDefinition {
     /** Path or glob to agent-written files */
     file: string;
@@ -843,6 +979,25 @@ interface WritebackDefinition {
     stateStore?: WritebackStateStore;
     /** Called after entries are processed for a file. Useful for archival. */
     onArchive?: (filePath: string) => void;
+    /**
+     * Optional validation hook. Called before `persist` for each entry.
+     * Return `{ pass: true, score }` to allow the write, or
+     * `{ pass: false, score, reason }` to reject it.
+     *
+     * When omitted, all parsed entries are persisted without validation.
+     */
+    validate?: (entry: unknown) => WritebackValidationResult | Promise<WritebackValidationResult>;
+    /**
+     * Minimum score threshold. Entries with `score < rejectBelow` are
+     * automatically rejected even if `validate` returns `pass: true`.
+     * Only meaningful when `validate` is set. Default: 0 (no threshold).
+     */
+    rejectBelow?: number;
+    /**
+     * Called for each entry that fails validation.
+     * Useful for logging or auditing rejected writes.
+     */
+    onReject?: (entry: unknown, result: WritebackValidationResult) => void;
 }
 interface QueryOptions {
     /**
@@ -1154,6 +1309,8 @@ declare class Lattice {
     private readonly _encryptedTableColumns;
     /** Raw encryption key passphrase from constructor options. */
     private readonly _encryptionKeyRaw?;
+    /** Current task context string for relevance filtering. */
+    private _taskContext;
     private readonly _auditHandlers;
     private readonly _renderHandlers;
     private readonly _writebackHandlers;
@@ -1178,6 +1335,13 @@ declare class Lattice {
      */
     migrate(migrations: Migration[]): Promise<void>;
     close(): void;
+    /**
+     * Set the current task context string. Tables with a `relevanceFilter`
+     * will use this value to filter rows before rendering.
+     */
+    setTaskContext(context: string): this;
+    /** Return the current task context string. */
+    getTaskContext(): string;
     private _setupEncryption;
     /** Encrypt applicable columns in a row before writing. Returns a new row. */
     private _encryptRow;
@@ -1258,6 +1422,22 @@ declare class Lattice {
     buildReport(config: ReportConfig): Promise<ReportResult>;
     /** Parse duration shorthand ('8h', '24h', '7d') into ISO timestamp. */
     private _resolveSince;
+    /**
+     * Update reward scores for a row. The total reward is recalculated as
+     * the running average across all reward calls. Requires `rewardTracking`
+     * on the table definition.
+     */
+    reward(table: string, id: PkLookup, scores: RewardScores): Promise<void>;
+    /**
+     * Search for rows by semantic similarity. Requires `embeddings` config
+     * on the table definition.
+     *
+     * @param table  - Table to search
+     * @param query  - Natural-language query text
+     * @param opts   - Search options (topK, minScore)
+     * @returns Matching rows with similarity scores, sorted best-first.
+     */
+    search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
@@ -1297,6 +1477,11 @@ declare class Lattice {
     private _buildFilters;
     /** Returns a rejected Promise if not initialized; null if ready. */
     private _fireWriteHooks;
+    /**
+     * Update or remove the embedding for a row.
+     * No-op if the table doesn't have `embeddings` configured.
+     */
+    private _syncEmbedding;
     private _notInitError;
     /**
      * Returns a rejected Promise if any of the given column names are not present
@@ -1512,6 +1697,25 @@ declare function parseConfigString(yamlContent: string, configDir: string): Pars
 
 declare function contentHash(content: string): string;
 
+/**
+ * Estimate the number of tokens in a string using a fast heuristic.
+ * Uses ~4 characters per token, a reasonable approximation for English
+ * text with typical LLM tokenizers (BPE/ByteBPE).
+ *
+ * Users who need exact counts should pre-process with their own tokenizer
+ * and use the `filter` hook to manually limit rows.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Apply a token budget to rendered output.
+ * If the full render exceeds the budget, rows are sorted by priority,
+ * pruned via binary search, and re-rendered. A truncation footer is
+ * appended so the consuming agent knows context was limited.
+ *
+ * @returns Final content string, possibly with truncation footer.
+ */
+declare function applyTokenBudget(rows: Row[], renderFn: (rows: Row[]) => string, budget: number, prioritizeBy?: string | ((a: Row, b: Row) => number)): string;
+
 /**
  * Fix legacy schema conflicts before Lattice init().
  *
@@ -1827,4 +2031,4 @@ declare function autoUpdate(opts?: {
     quiet?: boolean;
 }): Promise<AutoUpdateResult>;
 
-export { type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type Row, type SecurityOptions, type SeedConfig, type SeedLinkSpec, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type UpsertByNaturalKeyOptions, type WatchOptions, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, applyWriteEntry, autoUpdate, contentHash, createReadOnlyHeader, createSQLiteStateStore, decrypt, deriveKey, encrypt, entityFileNames, fixSchemaConflicts, frontmatter, generateEntryId, generateWriteEntryId, isEncrypted, isV1EntityFiles, manifestPath, markdownTable, normalizeEntityFiles, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };
+export { type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BuiltinTemplateName, type CleanupOptions, type CleanupResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type EmbeddingsConfig, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type Filter, type FilterOp, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type Migration, type MultiTableDefinition, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceQueryOptions, type StopFn, type SyncResult, type TableDefinition, type TemplateRenderSpec, type UpsertByNaturalKeyOptions, type WatchOptions, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, applyTokenBudget, applyWriteEntry, autoUpdate, contentHash, createReadOnlyHeader, createSQLiteStateStore, decrypt, deriveKey, encrypt, entityFileNames, estimateTokens, fixSchemaConflicts, frontmatter, generateEntryId, generateWriteEntryId, isEncrypted, isV1EntityFiles, manifestPath, markdownTable, normalizeEntityFiles, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, readManifest, slugify, truncate, validateEntryId, writeManifest };