@outsidedata/dolex 0.1.0

package/dist/src/query-engine/schema-loader.js

@@ -0,0 +1,144 @@
+/**
+ * Schema Loader — Loads and analyzes data schemas from SQLite databases.
+ *
+ * Extracted from loadDataset() and inferColumnType() in the POC.
+ * Works with DataSchema/DataTable/DataColumn types from types.ts.
+ */
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse } from 'papaparse';
+/**
+ * Infer column type from name, sample values, and cardinality.
+ */
+export function inferColumnType(name, samples, uniqueCount, totalRows) {
+    const lower = name.toLowerCase();
+    // ID detection
+    if (lower === 'id' || lower.endsWith('_id') || (lower.endsWith('id') && uniqueCount > totalRows * 0.5)) {
+        if (lower.endsWith('id'))
+            return 'id';
+    }
+    // Date detection
+    if (lower.includes('date') || lower.includes('time') || lower.includes('year') || lower.includes('timestamp')) {
+        return 'date';
+    }
+    // Numeric detection — check if samples are numbers
+    const numericSamples = samples.filter(s => s !== '' && !isNaN(Number(s)));
+    if (numericSamples.length > samples.length * 0.7) {
+        return 'numeric';
+    }
+    return 'categorical';
+}
+/**
+ * Analyze a single table's columns in the database.
+ */
+function analyzeTableColumns(db, tableName, totalRows) {
+    const columns = [];
+    // Get column names from pragma
+    const colInfos = db.prepare(`PRAGMA table_info("${tableName}")`).all();
+    for (const colInfo of colInfos) {
+        const col = colInfo.name;
+        const sampleStmt = db.prepare(`SELECT DISTINCT "${col}" FROM "${tableName}" WHERE "${col}" IS NOT NULL AND "${col}" != '' LIMIT 30`);
+        const samples = sampleStmt.all().map((r) => String(r[col]));
+        const countStmt = db.prepare(`SELECT COUNT(DISTINCT "${col}") as cnt, COUNT(*) - COUNT("${col}") as nulls, COUNT(*) as total FROM "${tableName}"`);
+        const stats = countStmt.get();
+        const type = inferColumnType(col, samples, stats.cnt, totalRows);
+        columns.push({
+            name: col,
+            type,
+            sampleValues: samples.slice(0, 20),
+            uniqueCount: stats.cnt,
+            nullCount: stats.nulls,
+            totalCount: stats.total,
+        });
+    }
+    return columns;
+}
+/**
+ * Detect foreign keys by matching column names across tables.
+ */
+function detectForeignKeys(tables) {
+    const foreignKeys = [];
+    for (const table of tables) {
+        for (const col of table.columns) {
+            if (col.type === 'id' || col.name.toLowerCase().endsWith('id') || col.name.toLowerCase().endsWith('_id')) {
+                for (const otherTable of tables) {
+                    if (otherTable.name !== table.name) {
+                        const matchingCol = otherTable.columns.find(c => c.name === col.name);
+                        if (matchingCol) {
+                            foreignKeys.push({
+                                fromTable: table.name,
+                                fromColumn: col.name,
+                                toTable: otherTable.name,
+                                toColumn: matchingCol.name,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return foreignKeys;
+}
+/**
+ * Load a DataSchema from an existing SQLite database.
+ *
+ * Queries the database for table and column metadata, infers types,
+ * and detects foreign keys by column name matching.
+ */
+export function loadSchema(db, source) {
+    const tableRows = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`).all();
+    const tables = [];
+    for (const { name: tableName } of tableRows) {
+        const countResult = db.prepare(`SELECT COUNT(*) as cnt FROM "${tableName}"`).get();
+        const rowCount = countResult.cnt;
+        const columns = analyzeTableColumns(db, tableName, rowCount);
+        tables.push({
+            name: tableName,
+            columns,
+            rowCount,
+        });
+    }
+    const foreignKeys = detectForeignKeys(tables);
+    return { tables, foreignKeys, source };
+}
+/**
+ * Load CSV files from a directory into an in-memory SQLite database,
+ * then return both the database and its schema.
+ *
+ * Each CSV file becomes a table (filename without extension, sanitized).
+ * Large tables are capped at maxRows for performance.
+ */
+export function loadCsvToSqlite(csvDir, source, options) {
+    const maxRows = options?.maxRows ?? 50000;
+    const db = new Database(':memory:');
+    const csvFiles = fs.readdirSync(csvDir).filter(f => f.endsWith('.csv'));
+    for (const file of csvFiles) {
+        const tableName = file.replace('.csv', '').replace(/[^a-zA-Z0-9_]/g, '_');
+        const raw = fs.readFileSync(path.join(csvDir, file), 'utf-8');
+        const parsed = parse(raw, { header: true, skipEmptyLines: true });
+        let rows = parsed.data;
+        // Cap large tables
+        if (rows.length > maxRows) {
+            rows = rows.slice(0, maxRows);
+        }
+        if (rows.length === 0)
+            continue;
+        const colNames = Object.keys(rows[0]);
+        // Create table
+        const safeCols = colNames.map(c => `"${c}" TEXT`).join(', ');
+        db.exec(`CREATE TABLE IF NOT EXISTS "${tableName}" (${safeCols})`);
+        // Insert rows in a transaction
+        const placeholders = colNames.map(() => '?').join(', ');
+        const insert = db.prepare(`INSERT INTO "${tableName}" VALUES (${placeholders})`);
+        const insertMany = db.transaction((rowBatch) => {
+            for (const row of rowBatch) {
+                insert.run(...colNames.map(c => row[c] ?? null));
+            }
+        });
+        insertMany(rows);
+    }
+    const schema = loadSchema(db, source);
+    return { db, schema };
+}
+//# sourceMappingURL=schema-loader.js.map

package/dist/src/query-engine/schema-loader.js.map

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

package/dist/src/query-engine/session.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Session — Conversational follow-up context manager.
+ *
+ * NEW: Not in the POC. Stores recent queries + results per session.
+ * When a new query references prior context ("now show that by year",
+ * "drill into the Northeast"), it provides the previous selection
+ * as context to the LLM.
+ */
+import type { LLMColumnSelection } from '../types.js';
+export interface SessionEntry {
+    query: string;
+    selection: LLMColumnSelection;
+    chartTypeHint: string;
+    timestamp: number;
+}
+export interface SessionContext {
+    previousQuery: string;
+    previousSelection: LLMColumnSelection;
+}
+/**
+ * Manages session state for conversational query follow-ups.
+ *
+ * Each session stores a bounded history of recent queries and selections.
+ * When the LLM selector needs context for a follow-up query, the session
+ * provides the most recent selection as reference.
+ */
+export declare class SessionManager {
+    /** Map of session ID to ordered list of entries (most recent last). */
+    private sessions;
+    /** Maximum number of entries to keep per session. */
+    private maxEntries;
+    /** Maximum age of a session in milliseconds before it's purged. */
+    private maxAgeMs;
+    constructor(options?: {
+        maxEntries?: number;
+        maxAgeMs?: number;
+    });
+    /**
+     * Record a completed query and its selection in the session.
+     */
+    addEntry(sessionId: string, entry: Omit<SessionEntry, 'timestamp'>): void;
+    /**
+     * Get the context from the most recent query in a session.
+     *
+     * Returns null if the session doesn't exist, is empty, or has expired.
+     */
+    getContext(sessionId: string): SessionContext | null;
+    /**
+     * Get full session history (for debugging or advanced context).
+     */
+    getHistory(sessionId: string): SessionEntry[];
+    /**
+     * Clear a specific session.
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Purge all expired sessions. Call periodically to prevent memory leaks.
+     */
+    purgeExpired(): number;
+    /**
+     * Detect if a query is likely a follow-up that references prior context.
+     *
+     * Looks for pronouns and relative references like:
+     * - "that", "those", "the same", "it"
+     * - "now show", "also show", "instead"
+     * - "drill into", "break down", "by year", "by month"
+     * - "but for", "but with", "and also"
+     */
+    static isFollowUp(query: string): boolean;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/src/query-engine/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/query-engine/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,kBAAkB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAA0C;IAE1D,qDAAqD;IACrD,OAAO,CAAC,UAAU,CAAS;IAE3B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAKhE;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,IAAI;IAczE;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAkBpD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAI7C;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,YAAY,IAAI,MAAM;IActB;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAoB1C"}

package/dist/src/query-engine/session.js

@@ -0,0 +1,117 @@
+/**
+ * Session — Conversational follow-up context manager.
+ *
+ * NEW: Not in the POC. Stores recent queries + results per session.
+ * When a new query references prior context ("now show that by year",
+ * "drill into the Northeast"), it provides the previous selection
+ * as context to the LLM.
+ */
+/**
+ * Manages session state for conversational query follow-ups.
+ *
+ * Each session stores a bounded history of recent queries and selections.
+ * When the LLM selector needs context for a follow-up query, the session
+ * provides the most recent selection as reference.
+ */
+export class SessionManager {
+    /** Map of session ID to ordered list of entries (most recent last). */
+    sessions = new Map();
+    /** Maximum number of entries to keep per session. */
+    maxEntries;
+    /** Maximum age of a session in milliseconds before it's purged. */
+    maxAgeMs;
+    constructor(options) {
+        this.maxEntries = options?.maxEntries ?? 20;
+        this.maxAgeMs = options?.maxAgeMs ?? 30 * 60 * 1000; // 30 minutes default
+    }
+    /**
+     * Record a completed query and its selection in the session.
+     */
+    addEntry(sessionId, entry) {
+        if (!this.sessions.has(sessionId)) {
+            this.sessions.set(sessionId, []);
+        }
+        const entries = this.sessions.get(sessionId);
+        entries.push({ ...entry, timestamp: Date.now() });
+        // Trim to max entries
+        if (entries.length > this.maxEntries) {
+            entries.splice(0, entries.length - this.maxEntries);
+        }
+    }
+    /**
+     * Get the context from the most recent query in a session.
+     *
+     * Returns null if the session doesn't exist, is empty, or has expired.
+     */
+    getContext(sessionId) {
+        const entries = this.sessions.get(sessionId);
+        if (!entries || entries.length === 0)
+            return null;
+        const latest = entries[entries.length - 1];
+        // Check if session has expired
+        if (Date.now() - latest.timestamp > this.maxAgeMs) {
+            this.sessions.delete(sessionId);
+            return null;
+        }
+        return {
+            previousQuery: latest.query,
+            previousSelection: latest.selection,
+        };
+    }
+    /**
+     * Get full session history (for debugging or advanced context).
+     */
+    getHistory(sessionId) {
+        return this.sessions.get(sessionId) ?? [];
+    }
+    /**
+     * Clear a specific session.
+     */
+    clearSession(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /**
+     * Purge all expired sessions. Call periodically to prevent memory leaks.
+     */
+    purgeExpired() {
+        const now = Date.now();
+        let purged = 0;
+        for (const [sessionId, entries] of this.sessions) {
+            if (entries.length === 0 || now - entries[entries.length - 1].timestamp > this.maxAgeMs) {
+                this.sessions.delete(sessionId);
+                purged++;
+            }
+        }
+        return purged;
+    }
+    /**
+     * Detect if a query is likely a follow-up that references prior context.
+     *
+     * Looks for pronouns and relative references like:
+     * - "that", "those", "the same", "it"
+     * - "now show", "also show", "instead"
+     * - "drill into", "break down", "by year", "by month"
+     * - "but for", "but with", "and also"
+     */
+    static isFollowUp(query) {
+        const lower = query.toLowerCase();
+        const followUpPatterns = [
+            /\bthat\b/,
+            /\bthose\b/,
+            /\bthe same\b/,
+            /\bnow show\b/,
+            /\balso show\b/,
+            /\binstead\b/,
+            /\bdrill into\b/,
+            /\bbreak down\b/,
+            /\bbut for\b/,
+            /\bbut with\b/,
+            /\band also\b/,
+            /\bnow by\b/,
+            /\bsame but\b/,
+            /\bthis time\b/,
+        ];
+        return followUpPatterns.some(p => p.test(lower));
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/src/query-engine/session.js.map

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

package/dist/src/query-engine/sql-builder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SQL Builder — Build SQL from LLMColumnSelection.
+ *
+ * Extracted from buildSQL() and findJoinColumn() in the POC.
+ * Handles all query patterns: simple aggregation, filtering, multi-table joins,
+ * window functions, percentages, multi-measure.
+ *
+ * The _schemaRef global from the POC is eliminated — schema is passed explicitly.
+ */
+import type { DataSchema, LLMColumnSelection } from '../types.js';
+/**
+ * Find a shared column between two tables that can serve as a join key.
+ *
+ * Prefers ID columns (ending in "id") over other shared columns.
+ * Schema is passed explicitly (no global state).
+ */
+export declare function findJoinColumn(table1: string, table2: string, schema: DataSchema): string | null;
+/**
+ * Build a SQL query from a validated LLMColumnSelection.
+ *
+ * Handles these query patterns:
+ * - Scalar (no category)
+ * - Single-dimensional grouping (category only)
+ * - Two-dimensional grouping (category + series)
+ * - Single-dimensional + two measures
+ * - Two-dimensional + two measures
+ * - Percentage computed metric
+ * - Top N per group (window function with ROW_NUMBER)
+ * - Multi-table JOINs
+ * - WHERE filters (=, LIKE, IN)
+ */
+export declare function buildSQL(selection: LLMColumnSelection, schema: DataSchema): string;
+//# sourceMappingURL=sql-builder.d.ts.map

package/dist/src/query-engine/sql-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-builder.d.ts","sourceRoot":"","sources":["../../../src/query-engine/sql-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,GACjB,MAAM,GAAG,IAAI,CAYf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAsGlF"}

package/dist/src/query-engine/sql-builder.js

@@ -0,0 +1,146 @@
+/**
+ * SQL Builder — Build SQL from LLMColumnSelection.
+ *
+ * Extracted from buildSQL() and findJoinColumn() in the POC.
+ * Handles all query patterns: simple aggregation, filtering, multi-table joins,
+ * window functions, percentages, multi-measure.
+ *
+ * The _schemaRef global from the POC is eliminated — schema is passed explicitly.
+ */
+/**
+ * Find a shared column between two tables that can serve as a join key.
+ *
+ * Prefers ID columns (ending in "id") over other shared columns.
+ * Schema is passed explicitly (no global state).
+ */
+export function findJoinColumn(table1, table2, schema) {
+    const t1 = schema.tables.find(t => t.name === table1);
+    const t2 = schema.tables.find(t => t.name === table2);
+    if (!t1 || !t2)
+        return null;
+    const cols1 = t1.columns.map(c => c.name);
+    const cols2 = t2.columns.map(c => c.name);
+    const shared = cols1.filter(c => cols2.includes(c));
+    // Prefer ID columns
+    const idCol = shared.find(c => c.toLowerCase().endsWith('id'));
+    return idCol || shared[0] || null;
+}
+/**
+ * Build a SQL query from a validated LLMColumnSelection.
+ *
+ * Handles these query patterns:
+ * - Scalar (no category)
+ * - Single-dimensional grouping (category only)
+ * - Two-dimensional grouping (category + series)
+ * - Single-dimensional + two measures
+ * - Two-dimensional + two measures
+ * - Percentage computed metric
+ * - Top N per group (window function with ROW_NUMBER)
+ * - Multi-table JOINs
+ * - WHERE filters (=, LIKE, IN)
+ */
+export function buildSQL(selection, schema) {
+    const val = `"${selection.value_column.table}"."${selection.value_column.column}"`;
+    const cat = selection.category_column
+        ? `"${selection.category_column.table}"."${selection.category_column.column}"`
+        : null;
+    const series = selection.series_column
+        ? `"${selection.series_column.table}"."${selection.series_column.column}"`
+        : null;
+    // Collect all referenced tables
+    const tables = new Set();
+    tables.add(selection.value_column.table);
+    if (selection.category_column)
+        tables.add(selection.category_column.table);
+    if (selection.series_column)
+        tables.add(selection.series_column.table);
+    if (selection.value_column_2)
+        tables.add(selection.value_column_2.table);
+    for (const f of selection.filters || [])
+        tables.add(f.table);
+    // Build JOIN chain — connect all tables through shared columns
+    const tableList = [...tables];
+    let fromClause;
+    if (tableList.length === 1) {
+        fromClause = `"${tableList[0]}"`;
+    }
+    else {
+        const joined = new Set([tableList[0]]);
+        fromClause = `"${tableList[0]}"`;
+        const remaining = tableList.slice(1);
+        for (const table of remaining) {
+            let connected = false;
+            for (const jt of joined) {
+                const sharedCol = findJoinColumn(jt, table, schema);
+                if (sharedCol) {
+                    fromClause += ` JOIN "${table}" ON "${jt}"."${sharedCol}" = "${table}"."${sharedCol}"`;
+                    joined.add(table);
+                    connected = true;
+                    break;
+                }
+            }
+            if (!connected) {
+                // Cross join as fallback (comma-separated tables)
+                fromClause += `, "${table}"`;
+                joined.add(table);
+            }
+        }
+    }
+    // WHERE clause — handle IN operator
+    const wheres = (selection.filters || []).map(f => {
+        if (f.op === 'IN' || f.op === 'in') {
+            const vals = f.value
+                .split(',')
+                .map((v) => `'${v.trim()}'`)
+                .join(', ');
+            return `"${f.table}"."${f.column}" IN (${vals})`;
+        }
+        return `"${f.table}"."${f.column}" ${f.op} '${f.value}'`;
+    });
+    const whereClause = wheres.length > 0 ? `WHERE ${wheres.join(' AND ')}` : '';
+    // Aggregate expression for primary value
+    const agg = selection.aggregate === 'count'
+        ? `COUNT(${val})`
+        : `${selection.aggregate.toUpperCase()}(CAST(${val} AS REAL))`;
+    // Second aggregate if present
+    const val2 = selection.value_column_2
+        ? `"${selection.value_column_2.table}"."${selection.value_column_2.column}"`
+        : null;
+    const agg2 = val2 && selection.aggregate_2
+        ? selection.aggregate_2 === 'count'
+            ? `COUNT(${val2})`
+            : `${selection.aggregate_2.toUpperCase()}(CAST(${val2} AS REAL))`
+        : null;
+    // Build query based on pattern
+    if (selection.top_n_per_group && cat && series) {
+        // Top N per group using window function
+        const innerSelect = `SELECT ${cat} AS category, ${series} AS series, ${agg} AS value, ROW_NUMBER() OVER (PARTITION BY ${cat} ORDER BY ${agg} DESC) AS rn FROM ${fromClause} ${whereClause} GROUP BY ${cat}, ${series}`;
+        return `SELECT category, series, value FROM (${innerSelect}) WHERE rn <= ${selection.top_n_per_group} ORDER BY category ${selection.sort}, value DESC LIMIT ${selection.limit || 100}`;
+    }
+    else if (selection.computed === 'percentage' && cat) {
+        // Percentage: value as share of total
+        const totalSubq = `(SELECT ${agg} FROM ${fromClause} ${whereClause})`;
+        return `SELECT ${cat} AS category, ${series ? `${series} AS series,` : ''} ${agg} AS value, ROUND(CAST(${agg} AS REAL) * 100.0 / ${totalSubq}, 2) AS percentage FROM ${fromClause} ${whereClause} GROUP BY ${cat}${series ? `, ${series}` : ''} ORDER BY percentage ${selection.sort} LIMIT ${selection.limit || 50}`;
+    }
+    else if (cat && series && agg2) {
+        // Two-dimensional + two measures
+        return `SELECT ${cat} AS category, ${series} AS series, ${agg} AS value, ${agg2} AS value_2 FROM ${fromClause} ${whereClause} GROUP BY ${cat}, ${series} ORDER BY ${cat} ${selection.sort}, value DESC LIMIT ${selection.limit || 50}`;
+    }
+    else if (cat && agg2) {
+        // Single-dimensional + two measures
+        return `SELECT ${cat} AS category, ${agg} AS value, ${agg2} AS value_2 FROM ${fromClause} ${whereClause} GROUP BY ${cat} ORDER BY value ${selection.sort} LIMIT ${selection.limit || 20}`;
+    }
+    else if (cat && series) {
+        // Two-dimensional grouping
+        return `SELECT ${cat} AS category, ${series} AS series, ${agg} AS value FROM ${fromClause} ${whereClause} GROUP BY ${cat}, ${series} ORDER BY ${cat} ${selection.sort}, value DESC LIMIT ${selection.limit || 50}`;
+    }
+    else if (cat) {
+        // Single-dimensional grouping
+        return `SELECT ${cat} AS category, ${agg} AS value FROM ${fromClause} ${whereClause} GROUP BY ${cat} ORDER BY value ${selection.sort} LIMIT ${selection.limit || 20}`;
+    }
+    else {
+        // Scalar
+        return `SELECT ${agg} AS value FROM ${fromClause} ${whereClause}`;
+    }
+}
+//# sourceMappingURL=sql-builder.js.map

package/dist/src/query-engine/sql-builder.js.map

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

package/dist/src/query-engine/validator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validator — Validate LLM selections against schema.
+ *
+ * Extracted from validateSelection() and editDistance() in the POC.
+ * Hard gate + auto-correct with edit distance for minor typos.
+ */
+import type { DataSchema, LLMColumnSelection } from '../types.js';
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    corrected: LLMColumnSelection;
+}
+/**
+ * Levenshtein edit distance between two strings.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * Validate that LLM-selected columns actually exist in the schema.
+ *
+ * For each column reference:
+ * 1. If exact match found, it passes.
+ * 2. If no exact match, find closest match by edit distance.
+ *    - If distance <= 3, auto-correct and log the correction.
+ *    - If distance > 3, mark as invalid (hallucinated column).
+ *
+ * Returns { valid, errors, corrected } where `corrected` has any fixable typos resolved.
+ */
+export declare function validateSelection(selection: LLMColumnSelection, schema: DataSchema): ValidationResult;
+//# sourceMappingURL=validator.d.ts.map

package/dist/src/query-engine/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/query-engine/validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAc,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAkBzD;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,UAAU,GACjB,gBAAgB,CAqDlB"}