nttp 1.0.0

package/dist/executor.js

@@ -0,0 +1,395 @@
+/**
+ * Query execution, SQL generation, and schema inference.
+ * Main orchestration pipeline for NTTP.
+ */
+import { SQLGenerationError, SQLExecutionError, LLMError, } from './errors.js';
+/**
+ * JSON Schema for SQL generation (for structured outputs).
+ */
+const SQL_GENERATION_JSON_SCHEMA = {
+    type: 'object',
+    properties: {
+        sql: {
+            type: 'string',
+            description: 'The SQL query to execute',
+        },
+        params: {
+            type: 'array',
+            items: {
+                type: ['string', 'integer', 'number', 'boolean', 'null'],
+            },
+            description: 'Parameters for the SQL query',
+        },
+    },
+    required: ['sql', 'params'],
+    additionalProperties: false,
+};
+/**
+ * System prompt for SQL generation.
+ */
+const SQL_GENERATION_SYSTEM_PROMPT = `You are an expert SQL generator.
+Generate safe, read-only SQL queries from structured intents.
+
+{schema}
+
+Rules:
+- Use parameterized queries with ? placeholders for values
+- Add LIMIT clause (max 1000)
+- Only SELECT queries - no UPDATE, DELETE, DROP, ALTER, INSERT
+- Use proper JOINs for relationships between tables
+- Handle filters intelligently (e.g., status='active', created_at > date)
+
+Return JSON:
+{
+  "sql": "SELECT ... FROM ... WHERE ... LIMIT ?",
+  "params": [value1, value2, ...]
+}
+
+Examples:
+Intent: {"entity": "users", "operation": "list", "filters": {"status": "active"}, "limit": 10}
+Response: {"sql": "SELECT * FROM users WHERE status = ? LIMIT ?", "params": ["active", 10]}
+
+Intent: {"entity": "orders", "operation": "count", "filters": {"status": "pending"}}
+Response: {"sql": "SELECT COUNT(*) as count FROM orders WHERE status = ?", "params": ["pending"]}
+`;
+/**
+ * Service for executing queries and managing SQL generation.
+ */
+export class QueryExecutor {
+    db;
+    llm;
+    cache;
+    l1Cache;
+    l2Cache;
+    defaultLimit = 100;
+    constructor(db, llm, cache, l1Cache, l2Cache) {
+        this.db = db;
+        this.llm = llm;
+        this.cache = cache;
+        this.l1Cache = l1Cache;
+        this.l2Cache = l2Cache;
+    }
+    /**
+     * Execute query with v2 3-layer caching.
+     */
+    async execute(options) {
+        const startTime = Date.now();
+        const { query, intent, useCache, forceNewSchema } = options;
+        // If v2 not enabled, fall back to v1 behavior
+        if (!this.l1Cache && !this.l2Cache) {
+            return this.executeV1(options);
+        }
+        // ─────────────────────────────────────────────────────────
+        // L1: EXACT MATCH (hash-based cache)
+        // Cost: $0.00 | Latency: <1ms
+        // ─────────────────────────────────────────────────────────
+        if (this.l1Cache && useCache && !forceNewSchema) {
+            const l1Hit = this.l1Cache.get(query);
+            if (l1Hit) {
+                const data = await this.executeRaw(l1Hit.sql, l1Hit.params);
+                const meta = {
+                    cacheLayer: 1,
+                    cost: 0,
+                    latency: Date.now() - startTime,
+                };
+                return {
+                    query,
+                    data,
+                    schemaId: l1Hit.schemaId,
+                    cacheHit: true,
+                    intent,
+                    sql: l1Hit.sql,
+                    params: l1Hit.params,
+                    meta,
+                };
+            }
+        }
+        // ─────────────────────────────────────────────────────────
+        // L2: SEMANTIC MATCH (embedding-based similarity)
+        // Cost: ~$0.0001 | Latency: 50-100ms
+        // ─────────────────────────────────────────────────────────
+        let l2Embedding;
+        if (this.l2Cache && useCache && !forceNewSchema) {
+            const { match, embedding } = await this.l2Cache.find(query);
+            l2Embedding = embedding; // Save for L3 if needed
+            if (match) {
+                const data = await this.executeRaw(match.result.sql, match.result.params);
+                // Promote to L1 for future exact matches
+                if (this.l1Cache) {
+                    this.l1Cache.set(query, match.result);
+                }
+                const meta = {
+                    cacheLayer: 2,
+                    cost: 0.0001,
+                    latency: Date.now() - startTime,
+                    similarity: match.similarity,
+                };
+                return {
+                    query,
+                    data,
+                    schemaId: match.result.schemaId,
+                    cacheHit: true,
+                    intent,
+                    sql: match.result.sql,
+                    params: match.result.params,
+                    meta,
+                };
+            }
+            // L2 miss - embedding saved for reuse in L3 to prevent double API billing
+        }
+        // ─────────────────────────────────────────────────────────
+        // L3: LLM FALLBACK (full pipeline)
+        // Cost: ~$0.01 | Latency: 2-3s
+        // ─────────────────────────────────────────────────────────
+        const schemaId = this.generateSchemaId(intent);
+        const { sql, params } = await this.generateSql(intent);
+        const data = await this.executeRaw(sql, params);
+        const result = {
+            schemaId,
+            sql,
+            params,
+            hitCount: 1,
+            createdAt: new Date(),
+            lastUsedAt: new Date(),
+        };
+        // Populate both L1 and L2 caches
+        if (this.l1Cache) {
+            this.l1Cache.set(query, result);
+        }
+        if (this.l2Cache) {
+            // Reuse embedding from L2 miss to prevent double API billing
+            if (l2Embedding) {
+                this.l2Cache.addWithEmbedding(query, l2Embedding, result);
+            }
+            else {
+                // L2 not checked (cache disabled or forced new schema)
+                await this.l2Cache.add(query, result);
+            }
+        }
+        // Also populate v1 schema cache (for backward compat)
+        const resultSchema = this.inferSchemaFromResults(data);
+        const schemaDefinition = {
+            schema_id: schemaId,
+            intent_pattern: intent.normalized_text,
+            generated_sql: sql,
+            sql_params: params,
+            result_schema: resultSchema,
+            use_count: 1,
+            created_at: new Date(),
+            last_used_at: new Date(),
+            example_queries: [query],
+            pinned: false,
+        };
+        await this.cache.set(schemaId, schemaDefinition);
+        const meta = {
+            cacheLayer: 3,
+            cost: 0.01,
+            latency: Date.now() - startTime,
+        };
+        return {
+            query,
+            data,
+            schemaId,
+            cacheHit: false,
+            intent,
+            sql,
+            params,
+            meta,
+        };
+    }
+    /**
+     * Execute query with v1 caching (legacy).
+     */
+    async executeV1(options) {
+        const { query, intent, useCache, forceNewSchema } = options;
+        // Generate schema ID from intent
+        const schemaId = this.generateSchemaId(intent);
+        // Check cache if enabled and not forcing new schema
+        if (useCache && !forceNewSchema) {
+            const cachedSchema = await this.cache.get(schemaId);
+            if (cachedSchema) {
+                // Cache hit - use cached SQL
+                const data = await this.executeRaw(cachedSchema.generated_sql, cachedSchema.sql_params);
+                // Update cache usage
+                await this.cache.updateUsage(schemaId);
+                await this.cache.addExampleQuery(schemaId, query);
+                return {
+                    query,
+                    data,
+                    schemaId,
+                    cacheHit: true,
+                    intent,
+                    sql: cachedSchema.generated_sql,
+                    params: cachedSchema.sql_params,
+                };
+            }
+        }
+        // Cache miss - generate and execute SQL
+        const { sql, params } = await this.generateSql(intent);
+        const data = await this.executeRaw(sql, params);
+        // Infer schema from results
+        const resultSchema = this.inferSchemaFromResults(data);
+        // Store in cache
+        const schemaDefinition = {
+            schema_id: schemaId,
+            intent_pattern: intent.normalized_text,
+            generated_sql: sql,
+            sql_params: params,
+            result_schema: resultSchema,
+            use_count: 1,
+            created_at: new Date(),
+            last_used_at: new Date(),
+            example_queries: [query],
+            pinned: false,
+        };
+        await this.cache.set(schemaId, schemaDefinition);
+        return {
+            query,
+            data,
+            schemaId,
+            cacheHit: false,
+            intent,
+            sql,
+            params,
+        };
+    }
+    /**
+     * Generate SQL query from intent.
+     */
+    async generateSql(intent) {
+        try {
+            // Prepare intent for LLM
+            const intentDict = {
+                entity: intent.entity,
+                operation: intent.operation,
+                filters: intent.filters,
+                limit: intent.limit || this.defaultLimit,
+                fields: intent.fields,
+                sort: intent.sort,
+            };
+            const schemaDescription = await this.getSchemaDescription();
+            const systemPrompt = SQL_GENERATION_SYSTEM_PROMPT.replace('{schema}', schemaDescription);
+            // Call LLM to generate SQL
+            const result = await this.llm.callStructured(`Generate SQL for this intent:\n${JSON.stringify(intentDict, null, 2)}`, systemPrompt, SQL_GENERATION_JSON_SCHEMA, 0.0);
+            // Validate SQL safety
+            this.validateSqlSafety(result.sql);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof LLMError) {
+                throw new SQLGenerationError(`Failed to generate SQL: ${error}`);
+            }
+            throw new SQLGenerationError(`SQL generation failed: ${error}`);
+        }
+    }
+    /**
+     * Execute raw SQL query.
+     */
+    async executeRaw(sql, params = []) {
+        try {
+            const result = await this.db.raw(sql, params);
+            // Normalize different dialect return formats
+            if (Array.isArray(result)) {
+                return result;
+            }
+            if (result.rows)
+                return result.rows; // PostgreSQL
+            if (Array.isArray(result[0]))
+                return result[0]; // MySQL
+            if (result.recordset)
+                return result.recordset; // SQL Server
+            return [];
+        }
+        catch (error) {
+            throw new SQLExecutionError(`Query failed: ${error}`);
+        }
+    }
+    /**
+     * Validate SQL safety (read-only).
+     */
+    validateSqlSafety(sql) {
+        const dangerous = [
+            /\bUPDATE\b/i,
+            /\bDELETE\b/i,
+            /\bDROP\b/i,
+            /\bALTER\b/i,
+            /\bINSERT\b/i,
+            /\bCREATE\b/i,
+        ];
+        for (const pattern of dangerous) {
+            if (pattern.test(sql)) {
+                throw new SQLGenerationError(`Dangerous SQL operation detected: ${pattern.source}`);
+            }
+        }
+        if (!sql.trim().match(/^(SELECT|WITH)\b/i)) {
+            throw new SQLGenerationError('SQL must start with SELECT or WITH');
+        }
+    }
+    /**
+     * Infer JSON schema from query results.
+     */
+    inferSchemaFromResults(results) {
+        if (results.length === 0) {
+            return {};
+        }
+        const schema = {};
+        const sample = results[0];
+        for (const [key, value] of Object.entries(sample)) {
+            schema[key] = { type: this.inferFieldType(value) };
+        }
+        return schema;
+    }
+    /**
+     * Infer type of a field value.
+     */
+    inferFieldType(value) {
+        if (value === null)
+            return 'null';
+        if (typeof value === 'boolean')
+            return 'boolean';
+        if (typeof value === 'number') {
+            return Number.isInteger(value) ? 'integer' : 'number';
+        }
+        if (typeof value === 'string') {
+            // Detect dates
+            if (/^\d{4}-\d{2}-\d{2}/.test(value)) {
+                return 'string'; // Keep as string, but could be 'date'
+            }
+            return 'string';
+        }
+        if (Array.isArray(value))
+            return 'array';
+        if (typeof value === 'object')
+            return 'object';
+        return 'string';
+    }
+    /**
+     * Get schema description for LLM.
+     */
+    async getSchemaDescription() {
+        const tables = await this.db
+            .select('name')
+            .from('sqlite_master')
+            .where('type', 'table')
+            .andWhere('name', 'not like', 'sqlite_%');
+        const lines = ['Database schema:'];
+        for (const { name } of tables) {
+            const columns = await this.db(name).columnInfo();
+            const columnNames = Object.keys(columns).join(', ');
+            lines.push(`- ${name} (${columnNames})`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Generate schema ID from intent (SHA256 hash).
+     */
+    generateSchemaId(intent) {
+        const crypto = require('crypto');
+        const hash = crypto
+            .createHash('sha256')
+            .update(intent.normalized_text)
+            .digest('hex');
+        return hash.substring(0, 16);
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACR,MAAM,aAAa,CAAC;AAOrB;;GAEG;AACH,MAAM,0BAA0B,GAAG;IACjC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,GAAG,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,0BAA0B;SACxC;QACD,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC;aACzD;YACD,WAAW,EAAE,8BAA8B;SAC5C;KACF;IACD,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,oBAAoB,EAAE,KAAK;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,4BAA4B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBpC,CAAC;AAwBF;;GAEG;AACH,MAAM,OAAO,aAAa;IAId;IACA;IACA;IACA;IACA;IAPF,YAAY,GAAW,GAAG,CAAC;IAEnC,YACU,EAAQ,EACR,GAAe,EACf,KAAkB,EAClB,OAAoB,EACpB,OAAuB;QAJvB,OAAE,GAAF,EAAE,CAAM;QACR,QAAG,GAAH,GAAG,CAAY;QACf,UAAK,GAAL,KAAK,CAAa;QAClB,YAAO,GAAP,OAAO,CAAa;QACpB,YAAO,GAAP,OAAO,CAAgB;IAC9B,CAAC;IAEJ;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,OAAuB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;QAE5D,8CAA8C;QAC9C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QAED,4DAA4D;QAC5D,qCAAqC;QACrC,8BAA8B;QAC9B,4DAA4D;QAC5D,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC5D,MAAM,IAAI,GAAgB;oBACxB,UAAU,EAAE,CAAC;oBACb,IAAI,EAAE,CAAC;oBACP,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;iBAChC,CAAC;gBACF,OAAO;oBACL,KAAK;oBACL,IAAI;oBACJ,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,QAAQ,EAAE,IAAI;oBACd,MAAM;oBACN,GAAG,EAAE,KAAK,CAAC,GAAG;oBACd,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,IAAI;iBACL,CAAC;YACJ,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,kDAAkD;QAClD,qCAAqC;QACrC,4DAA4D;QAC5D,IAAI,WAAiC,CAAC;QACtC,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;YAChD,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5D,WAAW,GAAG,SAAS,CAAC,CAAC,wBAAwB;YAEjD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAChC,KAAK,CAAC,MAAM,CAAC,GAAG,EAChB,KAAK,CAAC,MAAM,CAAC,MAAM,CACpB,CAAC;gBAEF,yCAAyC;gBACzC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBACxC,CAAC;gBAED,MAAM,IAAI,GAAgB;oBACxB,UAAU,EAAE,CAAC;oBACb,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;oBAC/B,UAAU,EAAE,KAAK,CAAC,UAAU;iBAC7B,CAAC;gBACF,OAAO;oBACL,KAAK;oBACL,IAAI;oBACJ,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ;oBAC/B,QAAQ,EAAE,IAAI;oBACd,MAAM;oBACN,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG;oBACrB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;oBAC3B,IAAI;iBACL,CAAC;YACJ,CAAC;YACD,0EAA0E;QAC5E,CAAC;QAED,4DAA4D;QAC5D,mCAAmC;QACnC,+BAA+B;QAC/B,4DAA4D;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAiB;YAC3B,QAAQ;YACR,GAAG;YACH,MAAM;YACN,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,UAAU,EAAE,IAAI,IAAI,EAAE;SACvB,CAAC;QAEF,iCAAiC;QACjC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,6DAA6D;YAC7D,IAAI,WAAW,EAAE,CAAC;gBAChB,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;YAC5D,CAAC;iBAAM,CAAC;gBACN,uDAAuD;gBACvD,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,sDAAsD;QACtD,MAAM,YAAY,GAAG,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,gBAAgB,GAAqB;YACzC,SAAS,EAAE,QAAQ;YACnB,cAAc,EAAE,MAAM,CAAC,eAAe;YACtC,aAAa,EAAE,GAAG;YAClB,UAAU,EAAE,MAAM;YAClB,aAAa,EAAE,YAAY;YAC3B,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,IAAI,IAAI,EAAE;YACtB,YAAY,EAAE,IAAI,IAAI,EAAE;YACxB,eAAe,EAAE,CAAC,KAAK,CAAC;YACxB,MAAM,EAAE,KAAK;SACd,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAgB;YACxB,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SAChC,CAAC;QACF,OAAO;YACL,KAAK;YACL,IAAI;YACJ,QAAQ;YACR,QAAQ,EAAE,KAAK;YACf,MAAM;YACN,GAAG;YACH,MAAM;YACN,IAAI;SACL,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,OAAuB;QACrC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;QAE5D,iCAAiC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAE/C,oDAAoD;QACpD,IAAI,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;YAChC,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,YAAY,EAAE,CAAC;gBACjB,6BAA6B;gBAC7B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAChC,YAAY,CAAC,aAAa,EAC1B,YAAY,CAAC,UAAU,CACxB,CAAC;gBAEF,qBAAqB;gBACrB,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;gBACvC,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAElD,OAAO;oBACL,KAAK;oBACL,IAAI;oBACJ,QAAQ;oBACR,QAAQ,EAAE,IAAI;oBACd,MAAM;oBACN,GAAG,EAAE,YAAY,CAAC,aAAa;oBAC/B,MAAM,EAAE,YAAY,CAAC,UAAU;iBAChC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,wCAAwC;QACxC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEhD,4BAA4B;QAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAEvD,iBAAiB;QACjB,MAAM,gBAAgB,GAAqB;YACzC,SAAS,EAAE,QAAQ;YACnB,cAAc,EAAE,MAAM,CAAC,eAAe;YACtC,aAAa,EAAE,GAAG;YAClB,UAAU,EAAE,MAAM;YAClB,aAAa,EAAE,YAAY;YAC3B,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,IAAI,IAAI,EAAE;YACtB,YAAY,EAAE,IAAI,IAAI,EAAE;YACxB,eAAe,EAAE,CAAC,KAAK,CAAC;YACxB,MAAM,EAAE,KAAK;SACd,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QAEjD,OAAO;YACL,KAAK;YACL,IAAI;YACJ,QAAQ;YACR,QAAQ,EAAE,KAAK;YACf,MAAM;YACN,GAAG;YACH,MAAM;SACP,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,MAAc;QAC9B,IAAI,CAAC;YACH,yBAAyB;YACzB,MAAM,UAAU,GAAG;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY;gBACxC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC;YAEF,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC5D,MAAM,YAAY,GAAG,4BAA4B,CAAC,OAAO,CACvD,UAAU,EACV,iBAAiB,CAClB,CAAC;YAEF,2BAA2B;YAC3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,cAAc,CAI1C,kCAAkC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EACvE,YAAY,EACZ,0BAA0B,EAC1B,GAAG,CACJ,CAAC;YAEF,sBAAsB;YACtB,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAEnC,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;gBAC9B,MAAM,IAAI,kBAAkB,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAC;YACnE,CAAC;YACD,MAAM,IAAI,kBAAkB,CAAC,0BAA0B,KAAK,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU,CACtB,GAAW,EACX,SAAsB,EAAE;QAExB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAE9C,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,OAAO,MAAsB,CAAC;YAChC,CAAC;YACD,IAAI,MAAM,CAAC,IAAI;gBAAE,OAAO,MAAM,CAAC,IAAoB,CAAC,CAAC,aAAa;YAClE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,MAAM,CAAC,CAAC,CAAiB,CAAC,CAAC,QAAQ;YACxE,IAAI,MAAM,CAAC,SAAS;gBAAE,OAAO,MAAM,CAAC,SAAyB,CAAC,CAAC,aAAa;YAE5E,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,iBAAiB,CAAC,iBAAiB,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,GAAW;QACnC,MAAM,SAAS,GAAG;YAChB,aAAa;YACb,aAAa;YACb,WAAW;YACX,YAAY;YACZ,aAAa;YACb,aAAa;SACd,CAAC;QAEF,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;YAChC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,kBAAkB,CAC1B,qCAAqC,OAAO,CAAC,MAAM,EAAE,CACtD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,kBAAkB,CAAC,oCAAoC,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED;;OAEG;IACK,sBAAsB,CAC5B,OAAqB;QAErB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAqC,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAE1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,KAAc;QACnC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QAClC,IAAI,OAAO,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;QACxD,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,eAAe;YACf,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,OAAO,QAAQ,CAAC,CAAC,sCAAsC;YACzD,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC;QACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC/C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB;QAChC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE;aACzB,MAAM,CAAC,MAAM,CAAC;aACd,IAAI,CAAC,eAAe,CAAC;aACrB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC;aACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;QAE5C,MAAM,KAAK,GAAa,CAAC,kBAAkB,CAAC,CAAC;QAE7C,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;YACjD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,WAAW,GAAG,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,MAAc;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM;aAChB,UAAU,CAAC,QAAQ,CAAC;aACpB,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;aAC9B,MAAM,CAAC,KAAK,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * NTTP - Natural Text Transfer Protocol
+ * Query databases with natural language using Claude AI
+ */
+export { NTTP } from './NTTP.js';
+export type { NTTPConfig, QueryOptions, QueryResult, Intent, SchemaDefinition, CacheStats, } from './types.js';
+export { IntentParseError, SQLGenerationError, SQLExecutionError, LLMError, CacheError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * NTTP - Natural Text Transfer Protocol
+ * Query databases with natural language using Claude AI
+ */
+export { NTTP } from './NTTP.js';
+export { IntentParseError, SQLGenerationError, SQLExecutionError, LLMError, CacheError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AASjC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/intent.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Intent parsing and normalization for cache key generation.
+ */
+import type { Intent, OperationType } from './types.js';
+import type { LLMService } from './llm.js';
+import type { FilterConditions, SortSpec } from './utils.js';
+/**
+ * Raw intent response from LLM before normalization.
+ */
+interface RawIntent {
+    entity: string;
+    operation: OperationType;
+    filters?: FilterConditions;
+    limit?: number | null;
+    fields?: string[] | null;
+    sort?: SortSpec | null;
+}
+/**
+ * Service for parsing natural language into structured intents.
+ */
+export declare class IntentParser {
+    private llm;
+    constructor(llm: LLMService);
+    /**
+     * Parse natural language query into structured intent.
+     *
+     * @param query Natural language query
+     * @param schemaDescription Database schema description
+     * @returns Structured Intent object
+     * @throws IntentParseError if parsing fails
+     */
+    parse(query: string, schemaDescription: string): Promise<Intent>;
+    /**
+     * Normalize intent dictionary to canonical form for cache key generation.
+     *
+     * CRITICAL: This algorithm must match Python exactly to ensure
+     * cache key compatibility between implementations.
+     *
+     * @param intentData Intent dictionary from LLM
+     * @returns Normalized string representation
+     */
+    normalizeIntentDict(intentData: RawIntent): string;
+    /**
+     * Generate unique schema ID from intent.
+     *
+     * CRITICAL: Must use exact same algorithm as Python (SHA256, first 16 chars)
+     * to ensure cache compatibility.
+     *
+     * @param intent Intent object
+     * @returns Schema ID (16-char hash)
+     */
+    generateSchemaId(intent: Intent): string;
+}
+export {};
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAyB,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAyCpF;;GAEG;AACH,UAAU,SAAS;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACvB;AAkCD;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,UAAU;IAEnC;;;;;;;OAOG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4CtE;;;;;;;;OAQG;IACH,mBAAmB,CAAC,UAAU,EAAE,SAAS,GAAG,MAAM;IAkDlD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAKzC"}

package/dist/intent.js

@@ -0,0 +1,183 @@
+/**
+ * Intent parsing and normalization for cache key generation.
+ */
+import crypto from 'crypto';
+import { IntentParseError, LLMError } from './errors.js';
+/**
+ * JSON Schema for intent parsing (for structured outputs).
+ */
+const INTENT_JSON_SCHEMA = {
+    type: 'object',
+    properties: {
+        entity: {
+            type: 'string',
+            description: 'Target table name (users, products, orders, or order_items)',
+        },
+        operation: {
+            type: 'string',
+            enum: ['list', 'count', 'aggregate', 'filter'],
+            description: 'Operation type',
+        },
+        filters: {
+            type: 'object',
+            description: 'Filter conditions as key-value pairs',
+            additionalProperties: false,
+        },
+        limit: {
+            type: ['integer', 'null'],
+            description: 'Result limit, or null for default',
+        },
+        fields: {
+            type: ['array', 'null'],
+            items: { type: 'string' },
+            description: 'Specific fields to return, or null for all fields',
+        },
+        sort: {
+            type: ['string', 'null'],
+            description: "Sort specification (e.g., 'created_at:desc'), or null",
+        },
+    },
+    required: ['entity', 'operation'],
+    additionalProperties: false,
+};
+/**
+ * System prompt for intent parsing.
+ */
+const INTENT_PARSE_SYSTEM_PROMPT = `You are an expert at parsing natural language database queries.
+Extract structured intent from user queries about an e-commerce database.
+
+{schema}
+
+Return JSON with this exact structure:
+{
+  "entity": "<table_name>",
+  "operation": "<list|count|aggregate|filter>",
+  "filters": {"<field>": "<value>"},
+  "limit": <number or null>,
+  "fields": [<field names>] or null,
+  "sort": "<field:asc|desc>" or null
+}
+
+Rules:
+- entity must be a valid table name from the schema above
+- operation: "list" for SELECT, "count" for COUNT, "aggregate" for SUM/AVG/etc
+- filters: extract conditions (e.g., "active users" -> {"status": "active"})
+- limit: extract limit if specified, otherwise null
+- fields: specific fields requested, or null for all fields
+- sort: sorting specification if mentioned
+
+Examples:
+- "get all active users" -> {"entity": "users", "operation": "list", "filters": {"status": "active"}, "limit": null}
+- "show me 10 products" -> {"entity": "products", "operation": "list", "filters": {}, "limit": 10}
+- "count pending orders" -> {"entity": "orders", "operation": "count", "filters": {"status": "pending"}, "limit": null}
+`;
+/**
+ * Service for parsing natural language into structured intents.
+ */
+export class IntentParser {
+    llm;
+    constructor(llm) {
+        this.llm = llm;
+    }
+    /**
+     * Parse natural language query into structured intent.
+     *
+     * @param query Natural language query
+     * @param schemaDescription Database schema description
+     * @returns Structured Intent object
+     * @throws IntentParseError if parsing fails
+     */
+    async parse(query, schemaDescription) {
+        try {
+            // Prepare system prompt with schema
+            const systemPrompt = INTENT_PARSE_SYSTEM_PROMPT.replace('{schema}', schemaDescription);
+            // Call LLM to parse intent with structured outputs (guaranteed schema compliance)
+            const result = await this.llm.callStructured(query, systemPrompt, INTENT_JSON_SCHEMA, 0.0);
+            // Ensure filters is a dict (guaranteed by schema, but defensive programming)
+            if (!result.filters) {
+                result.filters = {};
+            }
+            // Generate normalized text for cache key
+            const normalized = this.normalizeIntentDict(result);
+            // Create Intent object
+            const intent = {
+                entity: result.entity,
+                operation: result.operation,
+                filters: result.filters || {},
+                limit: result.limit,
+                fields: result.fields,
+                sort: result.sort,
+                normalized_text: normalized,
+            };
+            return intent;
+        }
+        catch (error) {
+            if (error instanceof LLMError) {
+                throw new IntentParseError(`Failed to understand query: ${error}`);
+            }
+            throw new IntentParseError(`Failed to parse query: ${error}`);
+        }
+    }
+    /**
+     * Normalize intent dictionary to canonical form for cache key generation.
+     *
+     * CRITICAL: This algorithm must match Python exactly to ensure
+     * cache key compatibility between implementations.
+     *
+     * @param intentData Intent dictionary from LLM
+     * @returns Normalized string representation
+     */
+    normalizeIntentDict(intentData) {
+        // Extract key components
+        const entity = (intentData.entity || '').toLowerCase().trim();
+        const operation = (intentData.operation || '').toLowerCase().trim();
+        const filters = intentData.filters || {};
+        const limit = intentData.limit;
+        const fields = intentData.fields || [];
+        const sort = intentData.sort;
+        // Normalize filters: sort keys and convert values to lowercase strings
+        const normalizedFilters = {};
+        for (const [key, value] of Object.entries(filters)) {
+            const keyClean = key.toLowerCase().trim();
+            const valueClean = typeof value === 'string' ? value.toLowerCase().trim() : String(value);
+            normalizedFilters[keyClean] = valueClean;
+        }
+        // Sort filter keys for consistency
+        const sortedFilters = Object.entries(normalizedFilters).sort(([a], [b]) => a.localeCompare(b));
+        // Build normalized representation
+        const parts = [`entity:${entity}`, `operation:${operation}`];
+        if (sortedFilters.length > 0) {
+            const filtersStr = sortedFilters.map(([k, v]) => `${k}=${v}`).join(',');
+            parts.push(`filters:${filtersStr}`);
+        }
+        if (limit) {
+            parts.push(`limit:${limit}`);
+        }
+        if (fields && fields.length > 0) {
+            const fieldsStr = fields
+                .map((f) => String(f).toLowerCase())
+                .sort()
+                .join(',');
+            parts.push(`fields:${fieldsStr}`);
+        }
+        if (sort) {
+            parts.push(`sort:${String(sort).toLowerCase()}`);
+        }
+        return parts.join('|');
+    }
+    /**
+     * Generate unique schema ID from intent.
+     *
+     * CRITICAL: Must use exact same algorithm as Python (SHA256, first 16 chars)
+     * to ensure cache compatibility.
+     *
+     * @param intent Intent object
+     * @returns Schema ID (16-char hash)
+     */
+    generateSchemaId(intent) {
+        const normalized = intent.normalized_text;
+        const hash = crypto.createHash('sha256').update(normalized).digest('hex');
+        return hash.substring(0, 16);
+    }
+}
+//# sourceMappingURL=intent.js.map