@outsidedata/dolex 0.1.0

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

@@ -0,0 +1,56 @@
+/**
+ * Query Engine — Public API that ties the full pipeline together.
+ *
+ * Pipeline:
+ *   1. CODE: Fuzzy-match user query to candidate columns (candidate-matcher)
+ *   2. LLM:  ONE call to select columns + aggregate + filters (llm-selector)
+ *   3. CODE: Validate column names — hard gate + auto-correct (validator)
+ *   4. If validation fails on hallucinated columns, auto-correction re-prompt (llm-selector)
+ *   5. CODE: Build SQL from template (sql-builder)
+ *   6. CODE: Execute SQL, determine chart type from result shape (chart-detector)
+ */
+import Database from 'better-sqlite3';
+import type { DataSchema, QueryRequest, QueryResult } from '../types.js';
+import { SessionManager } from './session.js';
+export interface QueryEngineOptions {
+    model?: string;
+    ollamaHost?: string;
+}
+export interface QueryError {
+    stage: 'candidates' | 'llm' | 'validation' | 'sql_build' | 'sql_execute' | 'chart';
+    message: string;
+    details?: any;
+}
+export type QueryEngineResult = {
+    success: true;
+    result: QueryResult;
+} | {
+    success: false;
+    error: QueryError;
+};
+export declare class QueryEngine {
+    private options;
+    private sessionManager;
+    constructor(options?: QueryEngineOptions);
+    /**
+     * Run the full query pipeline: candidates -> LLM selection -> validation -> SQL -> execute -> chart hint.
+     *
+     * Never throws — returns structured success/error results.
+     */
+    query(request: QueryRequest, schema: DataSchema, db: Database.Database): Promise<QueryEngineResult>;
+    /**
+     * Access the session manager for advanced session operations.
+     */
+    getSessionManager(): SessionManager;
+}
+export { loadSchema, loadCsvToSqlite } from './schema-loader.js';
+export { findCandidateColumns, extractFilterHints } from './candidate-matcher.js';
+export { askLLM, askLLMWithCorrection } from './llm-selector.js';
+export type { CandidateColumn, LLMSelectorOptions, LLMSelectorResult } from './llm-selector.js';
+export { validateSelection, editDistance } from './validator.js';
+export type { ValidationResult } from './validator.js';
+export { buildSQL, findJoinColumn } from './sql-builder.js';
+export { determineChartType } from './chart-detector.js';
+export { SessionManager } from './session.js';
+export type { SessionContext, SessionEntry } from './session.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EAEZ,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,YAAY,GAAG,KAAK,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,OAAO,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;CACrB,GAAG;IACF,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;CACnB,CAAA;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,cAAc,CAAiB;gBAE3B,OAAO,CAAC,EAAE,kBAAkB;IAQxC;;;;OAIG;IACG,KAAK,CACT,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,QAAQ,CAAC,QAAQ,GACpB,OAAO,CAAC,iBAAiB,CAAC;IAoK7B;;OAEG;IACH,iBAAiB,IAAI,cAAc;CAGpC;AAGD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACjE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,185 @@
+/**
+ * Query Engine — Public API that ties the full pipeline together.
+ *
+ * Pipeline:
+ *   1. CODE: Fuzzy-match user query to candidate columns (candidate-matcher)
+ *   2. LLM:  ONE call to select columns + aggregate + filters (llm-selector)
+ *   3. CODE: Validate column names — hard gate + auto-correct (validator)
+ *   4. If validation fails on hallucinated columns, auto-correction re-prompt (llm-selector)
+ *   5. CODE: Build SQL from template (sql-builder)
+ *   6. CODE: Execute SQL, determine chart type from result shape (chart-detector)
+ */
+import { findCandidateColumns } from './candidate-matcher.js';
+import { askLLM, askLLMWithCorrection } from './llm-selector.js';
+import { validateSelection } from './validator.js';
+import { buildSQL } from './sql-builder.js';
+import { determineChartType } from './chart-detector.js';
+import { SessionManager } from './session.js';
+export class QueryEngine {
+    options;
+    sessionManager;
+    constructor(options) {
+        this.options = {
+            model: options?.model ?? 'gemma3:27b',
+            ollamaHost: options?.ollamaHost ?? 'http://localhost:11434',
+        };
+        this.sessionManager = new SessionManager();
+    }
+    /**
+     * Run the full query pipeline: candidates -> LLM selection -> validation -> SQL -> execute -> chart hint.
+     *
+     * Never throws — returns structured success/error results.
+     */
+    async query(request, schema, db) {
+        const startTime = Date.now();
+        // Use request-level model override or engine default
+        const llmOptions = {
+            ...this.options,
+            model: request.model ?? this.options.model,
+        };
+        // ── Step 1: Find candidate columns ──
+        let candidates;
+        try {
+            candidates = findCandidateColumns(request.query, schema);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: { stage: 'candidates', message: err.message, details: err },
+            };
+        }
+        if (candidates.length === 0) {
+            return {
+                success: false,
+                error: {
+                    stage: 'candidates',
+                    message: 'No candidate columns found matching the query. Try rephrasing.',
+                },
+            };
+        }
+        // ── Get session context if this is a follow-up ──
+        let sessionContext = null;
+        if (request.sessionId && SessionManager.isFollowUp(request.query)) {
+            sessionContext = this.sessionManager.getContext(request.sessionId);
+        }
+        // ── Step 2: LLM selection ──
+        let selection;
+        let llmRetries = 0;
+        let correctionUsed = false;
+        try {
+            const llmResult = await askLLM(request.query, candidates, schema, llmOptions, sessionContext);
+            selection = llmResult.selection;
+            llmRetries = llmResult.retries;
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: { stage: 'llm', message: err.message, details: err },
+            };
+        }
+        // ── Step 3: Validate selection ──
+        let validation = validateSelection(selection, schema);
+        // ── Step 4: Auto-correction re-prompt if validation failed ──
+        if (!validation.valid) {
+            try {
+                // Serialize the failed selection as the "previous response" for the correction prompt
+                const previousResponseContent = JSON.stringify(selection, null, 2);
+                const correctionResult = await askLLMWithCorrection(request.query, candidates, schema, validation.errors, previousResponseContent, llmOptions, sessionContext);
+                selection = correctionResult.selection;
+                correctionUsed = true;
+                // Re-validate the corrected selection
+                validation = validateSelection(selection, schema);
+                if (!validation.valid) {
+                    return {
+                        success: false,
+                        error: {
+                            stage: 'validation',
+                            message: `Validation failed after correction re-prompt: ${validation.errors.join('; ')}`,
+                            details: { selection, errors: validation.errors },
+                        },
+                    };
+                }
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: {
+                        stage: 'validation',
+                        message: `Validation failed and correction re-prompt errored: ${err.message}. Original errors: ${validation.errors.join('; ')}`,
+                        details: { selection, validationErrors: validation.errors, correctionError: err },
+                    },
+                };
+            }
+        }
+        const finalSelection = validation.corrected;
+        // ── Step 5: Build SQL ──
+        let sql;
+        try {
+            sql = buildSQL(finalSelection, schema);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: { stage: 'sql_build', message: err.message, details: { selection: finalSelection } },
+            };
+        }
+        // ── Step 6: Execute SQL ──
+        let data;
+        let columns;
+        try {
+            data = db.prepare(sql).all();
+            columns = data.length > 0 ? Object.keys(data[0]) : [];
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: { stage: 'sql_execute', message: err.message, details: { sql, selection: finalSelection } },
+            };
+        }
+        // ── Step 7: Determine chart type ──
+        let chartTypeHint;
+        try {
+            chartTypeHint = determineChartType(data, finalSelection);
+        }
+        catch (err) {
+            // Chart detection should never really fail, but be safe
+            chartTypeHint = 'bar';
+        }
+        const executionTimeMs = Date.now() - startTime;
+        // ── Record in session for follow-ups ──
+        if (request.sessionId) {
+            this.sessionManager.addEntry(request.sessionId, {
+                query: request.query,
+                selection: finalSelection,
+                chartTypeHint,
+            });
+        }
+        return {
+            success: true,
+            result: {
+                sql,
+                data,
+                rowCount: data.length,
+                columns,
+                selection: finalSelection,
+                chartTypeHint,
+                executionTimeMs,
+            },
+        };
+    }
+    /**
+     * Access the session manager for advanced session operations.
+     */
+    getSessionManager() {
+        return this.sessionManager;
+    }
+}
+// ── Re-exports for convenience ──
+export { loadSchema, loadCsvToSqlite } from './schema-loader.js';
+export { findCandidateColumns, extractFilterHints } from './candidate-matcher.js';
+export { askLLM, askLLMWithCorrection } from './llm-selector.js';
+export { validateSelection, editDistance } from './validator.js';
+export { buildSQL, findJoinColumn } from './sql-builder.js';
+export { determineChartType } from './chart-detector.js';
+export { SessionManager } from './session.js';
+//# sourceMappingURL=index.js.map

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

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

package/dist/src/query-engine/llm-selector.d.ts

@@ -0,0 +1,47 @@
+/**
+ * LLM Selector — ONE LLM call to select columns from candidates.
+ *
+ * Extracted from askLLM() in the POC, with new improvements:
+ * - Garbage output detection (non-ASCII, non-JSON responses)
+ * - Single retry on garbage
+ * - Auto-correction re-prompt for hallucinated columns
+ */
+import type { DataSchema, DataColumn, LLMColumnSelection } from '../types.js';
+import type { SessionContext } from './session.js';
+/** Flat column descriptor with table context, used as LLM candidate input. */
+export type CandidateColumn = DataColumn & {
+    table: string;
+};
+export interface LLMSelectorOptions {
+    model?: string;
+    ollamaHost?: string;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+}
+export interface LLMSelectorResult {
+    selection: LLMColumnSelection;
+    retries: number;
+    correctionUsed: boolean;
+}
+/**
+ * Ask the LLM to select columns from candidates to answer the user's query.
+ *
+ * Pipeline:
+ * 1. Build prompt from candidates + schema
+ * 2. Call Ollama
+ * 3. If garbage output, retry once with same prompt
+ * 4. Parse JSON response
+ * 5. Return selection (validation happens separately in validator.ts)
+ *
+ * For auto-correction after validation failure, use askLLMWithCorrection().
+ */
+export declare function askLLM(query: string, candidates: CandidateColumn[], schema: DataSchema, options?: LLMSelectorOptions, sessionContext?: SessionContext | null): Promise<LLMSelectorResult>;
+/**
+ * Re-prompt the LLM with a correction when validation found hallucinated columns.
+ *
+ * Sends a focused prompt with the validation errors, asking the LLM to fix
+ * only the invalid references.
+ */
+export declare function askLLMWithCorrection(query: string, candidates: CandidateColumn[], schema: DataSchema, validationErrors: string[], previousResponseContent: string, options?: LLMSelectorOptions, sessionContext?: SessionContext | null): Promise<LLMSelectorResult>;
+//# sourceMappingURL=llm-selector.d.ts.map

package/dist/src/query-engine/llm-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-selector.d.ts","sourceRoot":"","sources":["../../../src/query-engine/llm-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAc,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAqMD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAsB5B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,UAAU,EAClB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,uBAAuB,EAAE,MAAM,EAC/B,OAAO,CAAC,EAAE,kBAAkB,EAC5B,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}

package/dist/src/query-engine/llm-selector.js

@@ -0,0 +1,223 @@
+/**
+ * LLM Selector — ONE LLM call to select columns from candidates.
+ *
+ * Extracted from askLLM() in the POC, with new improvements:
+ * - Garbage output detection (non-ASCII, non-JSON responses)
+ * - Single retry on garbage
+ * - Auto-correction re-prompt for hallucinated columns
+ */
+const DEFAULT_MODEL = 'gemma3:27b';
+const DEFAULT_HOST = 'http://localhost:11434';
+const DEFAULT_TEMPERATURE = 1.0;
+const DEFAULT_TOP_K = 64;
+const DEFAULT_TOP_P = 0.95;
+/**
+ * Detect garbage output: non-ASCII dominant, no JSON structure, or empty.
+ */
+function isGarbageOutput(content) {
+    if (!content || content.trim().length === 0)
+        return true;
+    // Check for non-ASCII dominance (e.g., model emitting binary/unicode noise)
+    const nonAsciiCount = (content.match(/[^\x00-\x7F]/g) || []).length;
+    const totalChars = content.length;
+    if (totalChars > 0 && nonAsciiCount / totalChars > 0.3)
+        return true;
+    // Must contain at least one '{' for JSON
+    if (!content.includes('{'))
+        return true;
+    return false;
+}
+/**
+ * Build the prompt for the LLM. This is the proven prompt structure from the POC.
+ */
+function buildPrompt(query, candidates, schema, sessionContext) {
+    const candidateDesc = candidates
+        .map(c => `  - ${c.table}.${c.name} (${c.type}, ${c.uniqueCount} unique values, samples: ${c.sampleValues.slice(0, 3).join(', ')})`)
+        .join('\n');
+    // Find relevant foreign keys for these tables
+    const relevantTables = [...new Set(candidates.map(c => c.table))];
+    const relevantFKs = schema.foreignKeys.filter(fk => relevantTables.includes(fk.fromTable) && relevantTables.includes(fk.toTable));
+    const fkDesc = relevantFKs.length > 0
+        ? `\nTable relationships:\n${relevantFKs.map(fk => `  - ${fk.fromTable}.${fk.fromColumn} -> ${fk.toTable}.${fk.toColumn}`).join('\n')}`
+        : '';
+    // Session context for conversational follow-ups
+    let sessionDesc = '';
+    if (sessionContext && sessionContext.previousSelection) {
+        const prev = sessionContext.previousSelection;
+        sessionDesc = `\n\nPrevious query context (for follow-up reference):
+  Previous query: "${sessionContext.previousQuery}"
+  Previous selection: category=${prev.category_column ? `${prev.category_column.table}.${prev.category_column.column}` : 'none'}, value=${prev.value_column.table}.${prev.value_column.column}, aggregate=${prev.aggregate}
+  If the current query references "that", "those", "the same", or modifies the previous query, use the previous selection as a starting point.\n`;
+    }
+    return `You are a data assistant. A user asked: "${query}"
+${sessionDesc}
+Here are the relevant columns from the database:
+${candidateDesc}
+${fkDesc}
+
+Pick columns to answer the user's question. Respond with ONLY valid JSON, no markdown:
+
+{
+  "category_column": {"table": "...", "column": "..."} or null,
+  "series_column": {"table": "...", "column": "..."} or null,
+  "value_column": {"table": "...", "column": "..."},
+  "value_column_2": {"table": "...", "column": "..."} or null,
+  "aggregate": "count" | "sum" | "avg" | "min" | "max",
+  "aggregate_2": "count" | "sum" | "avg" | "min" | "max" or null,
+  "computed": "percentage" | "ratio" | "difference" | null,
+  "top_n_per_group": number or null,
+  "filters": [{"table": "...", "column": "...", "op": "=", "value": "..."}] or [],
+  "sort": "desc" or "asc",
+  "limit": number between 5 and 100
+}
+
+Rules:
+- ONLY use table and column names from the list above. Do not invent columns.
+- category_column = X axis (year, team). series_column = groups within each category (driver within year). Use series_column when comparing multiple things over a dimension.
+- value_column_2 + aggregate_2: use when the question asks for two different metrics (e.g., "wins AND podiums", "count AND average").
+- computed: use "percentage" when the question asks "what percentage", "what share", "what proportion". Use "ratio" for "X per Y" or "rate". Use "difference" for "change" or "compared to".
+- top_n_per_group: use when the question says "top N per group" or "best N in each category" (e.g., "top 3 drivers per team").
+- If the question mentions a specific name, team, place, or year, add it as a filter. Use exact sample value spelling. Use "=" for exact, "LIKE" for partial.
+- Multiple filter values for same column: use "IN" as op with comma-separated values, e.g. {"op": "IN", "value": "Ferrari,McLaren,Red Bull"}`;
+}
+/**
+ * Build a correction re-prompt when validation fails on hallucinated columns.
+ */
+function buildCorrectionPrompt(originalPrompt, validationErrors, previousResponse) {
+    return `Your previous response had errors. Here is what went wrong:
+${validationErrors.map(e => `  - ${e}`).join('\n')}
+
+Your previous response was:
+${previousResponse}
+
+Please fix ONLY the invalid column references. Use ONLY columns from the original list.
+Respond with ONLY the corrected JSON, no markdown, no explanation.
+
+For reference, here is the original request:
+${originalPrompt}`;
+}
+/**
+ * Make a single LLM call to Ollama.
+ */
+async function callOllama(prompt, options) {
+    const model = options.model || DEFAULT_MODEL;
+    const host = options.ollamaHost || DEFAULT_HOST;
+    const response = await fetch(`${host}/api/chat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+            stream: false,
+            options: {
+                temperature: options.temperature ?? DEFAULT_TEMPERATURE,
+                top_k: options.topK ?? DEFAULT_TOP_K,
+                top_p: options.topP ?? DEFAULT_TOP_P,
+                num_ctx: 4096,
+                num_thread: model.includes('27b') ? 16 : undefined,
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Ollama request failed: ${response.status} ${response.statusText}`);
+    }
+    const result = await response.json();
+    return result.message?.content ?? '';
+}
+/**
+ * Parse the LLM response content into an LLMColumnSelection.
+ *
+ * Handles:
+ * - JSON embedded in markdown code blocks
+ * - Flat {table, column} normalization
+ * - Missing optional fields
+ */
+function parseResponse(content) {
+    // Extract JSON from response (handle markdown code blocks)
+    const jsonMatch = content.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        throw new Error(`No JSON in LLM response: ${content.slice(0, 200)}`);
+    }
+    const parsed = JSON.parse(jsonMatch[0]);
+    // Normalize: LLM sometimes returns flat {table, column} instead of nested structure
+    if (parsed.table && parsed.column && !parsed.value_column) {
+        return {
+            category_column: parsed.category_column || null,
+            series_column: parsed.series_column || null,
+            value_column: { table: parsed.table, column: parsed.column },
+            aggregate: parsed.aggregate || 'count',
+            filters: parsed.filters || [],
+            sort: parsed.sort || 'desc',
+            limit: parsed.limit || 20,
+        };
+    }
+    // Ensure value_column exists
+    if (!parsed.value_column) {
+        throw new Error(`LLM response missing value_column: ${JSON.stringify(parsed).slice(0, 200)}`);
+    }
+    // Normalize optional fields
+    if (!parsed.series_column)
+        parsed.series_column = null;
+    if (!parsed.value_column_2)
+        parsed.value_column_2 = null;
+    if (!parsed.aggregate_2)
+        parsed.aggregate_2 = null;
+    if (!parsed.computed)
+        parsed.computed = null;
+    if (!parsed.top_n_per_group)
+        parsed.top_n_per_group = null;
+    if (!parsed.filters)
+        parsed.filters = [];
+    if (!parsed.sort)
+        parsed.sort = 'desc';
+    if (!parsed.limit)
+        parsed.limit = 20;
+    return parsed;
+}
+/**
+ * Ask the LLM to select columns from candidates to answer the user's query.
+ *
+ * Pipeline:
+ * 1. Build prompt from candidates + schema
+ * 2. Call Ollama
+ * 3. If garbage output, retry once with same prompt
+ * 4. Parse JSON response
+ * 5. Return selection (validation happens separately in validator.ts)
+ *
+ * For auto-correction after validation failure, use askLLMWithCorrection().
+ */
+export async function askLLM(query, candidates, schema, options, sessionContext) {
+    const opts = options || {};
+    const prompt = buildPrompt(query, candidates, schema, sessionContext);
+    let retries = 0;
+    // First attempt
+    let content = await callOllama(prompt, opts);
+    // Garbage detection + single retry
+    if (isGarbageOutput(content)) {
+        retries = 1;
+        content = await callOllama(prompt, opts);
+        if (isGarbageOutput(content)) {
+            throw new Error(`LLM returned garbage output after retry. Content: ${content.slice(0, 200)}`);
+        }
+    }
+    const selection = parseResponse(content);
+    return { selection, retries, correctionUsed: false };
+}
+/**
+ * Re-prompt the LLM with a correction when validation found hallucinated columns.
+ *
+ * Sends a focused prompt with the validation errors, asking the LLM to fix
+ * only the invalid references.
+ */
+export async function askLLMWithCorrection(query, candidates, schema, validationErrors, previousResponseContent, options, sessionContext) {
+    const opts = options || {};
+    const originalPrompt = buildPrompt(query, candidates, schema, sessionContext);
+    const correctionPrompt = buildCorrectionPrompt(originalPrompt, validationErrors, previousResponseContent);
+    const content = await callOllama(correctionPrompt, opts);
+    if (isGarbageOutput(content)) {
+        throw new Error(`LLM returned garbage on correction re-prompt. Content: ${content.slice(0, 200)}`);
+    }
+    const selection = parseResponse(content);
+    return { selection, retries: 0, correctionUsed: true };
+}
+//# sourceMappingURL=llm-selector.js.map

package/dist/src/query-engine/llm-selector.js.map

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

package/dist/src/query-engine/schema-loader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 type { DataSchema, DataColumn, DataSourceInfo } from '../types.js';
+/**
+ * Infer column type from name, sample values, and cardinality.
+ */
+export declare function inferColumnType(name: string, samples: string[], uniqueCount: number, totalRows: number): DataColumn['type'];
+/**
+ * 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 declare function loadSchema(db: Database.Database, source: DataSourceInfo): DataSchema;
+/**
+ * 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 declare function loadCsvToSqlite(csvDir: string, source: DataSourceInfo, options?: {
+    maxRows?: number;
+}): {
+    db: Database.Database;
+    schema: DataSchema;
+};
+//# sourceMappingURL=schema-loader.d.ts.map

package/dist/src/query-engine/schema-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-loader.d.ts","sourceRoot":"","sources":["../../../src/query-engine/schema-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,OAAO,KAAK,EAAE,UAAU,EAAa,UAAU,EAAc,cAAc,EAAE,MAAM,aAAa,CAAC;AAEjG;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,UAAU,CAAC,MAAM,CAAC,CAoBpB;AAoED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU,CAuBpF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAsC/C"}