nttp 1.0.0

package/README.md

@@ -0,0 +1,245 @@
+# NTTP - Natural Text Transfer Protocol
+
+Query databases with natural language using Claude AI.
+
+## Installation
+
+```bash
+npm install nttp
+```
+
+You'll also need a database driver:
+
+```bash
+# SQLite
+npm install better-sqlite3
+
+# PostgreSQL
+npm install pg
+
+# MySQL
+npm install mysql2
+
+# SQL Server
+npm install mssql
+```
+
+## Quick Start
+
+```typescript
+import { NTTP } from 'nttp';
+
+const nttp = new NTTP({
+  database: {
+    client: 'pg',
+    connection: process.env.DATABASE_URL
+  },
+  anthropic: {
+    apiKey: process.env.ANTHROPIC_API_KEY
+  }
+});
+
+// Initialize (connects to database, builds schema cache)
+await nttp.init();
+
+// Query naturally!
+const users = await nttp.query("get all active users");
+console.log(users.data); // Array of users
+
+// Close when done
+await nttp.close();
+```
+
+## API Reference
+
+### `new NTTP(config)`
+
+Create a new NTTP instance.
+
+**Config:**
+```typescript
+{
+  database: {
+    client: 'pg' | 'mysql2' | 'better-sqlite3' | 'mssql',
+    connection: string | object  // Knex connection config
+  },
+  anthropic: {
+    apiKey: string,
+    model?: string,  // Default: 'claude-sonnet-4-5-20250929'
+    maxTokens?: number  // Default: 2048
+  },
+  limits?: {
+    maxQueryLength?: number,  // Default: 500
+    defaultLimit?: number,  // Default: 100
+    maxLimit?: number  // Default: 1000
+  }
+}
+```
+
+### `nttp.init()`
+
+Initialize NTTP. Must be called before querying.
+
+```typescript
+await nttp.init();
+```
+
+### `nttp.query(query, options?)`
+
+Execute a natural language query.
+
+```typescript
+const result = await nttp.query("show pending orders over $500");
+
+// Result structure:
+{
+  query: string,           // Original query
+  data: any[],            // Query results
+  schemaId: string,       // Cache key
+  cacheHit: boolean,      // Was cached?
+  executionTimeMs: number, // Execution time
+  intent: {...},          // Parsed intent
+  sql?: string,           // Generated SQL (debug)
+  params?: any[]          // SQL parameters (debug)
+}
+```
+
+**Options:**
+```typescript
+{
+  useCache?: boolean,       // Use cache (default: true)
+  forceNewSchema?: boolean  // Force new schema (default: false)
+}
+```
+
+### `nttp.explain(query)`
+
+Explain what SQL would be generated without executing.
+
+```typescript
+const explanation = await nttp.explain("top 10 customers by revenue");
+
+// Returns:
+{
+  query: string,
+  intent: {...},
+  sql: string,
+  params: any[],
+  schemaId: string,
+  cachedSchema: SchemaDefinition | null
+}
+```
+
+### Schema Management
+
+```typescript
+// List all cached schemas
+const schemas = await nttp.listSchemas();
+
+// Get specific schema
+const schema = await nttp.getSchema(schemaId);
+
+// Delete schema
+await nttp.deleteSchema(schemaId);
+
+// Pin schema (prevent eviction)
+await nttp.pinSchema(schemaId);
+
+// Unpin schema
+await nttp.unpinSchema(schemaId);
+
+// Get cache statistics
+const stats = await nttp.getCacheStats();
+```
+
+### Database Inspection
+
+```typescript
+// Get all tables
+const tables = await nttp.getTables();
+
+// Get table schema
+const schema = await nttp.getTableSchema('users');
+
+// Get schema description (for LLM)
+const description = nttp.getSchemaDescription();
+```
+
+## Example Queries
+
+```typescript
+// Simple queries
+await nttp.query("get all users");
+await nttp.query("show products");
+await nttp.query("list orders");
+
+// Filtered queries
+await nttp.query("active users only");
+await nttp.query("products in Electronics category");
+await nttp.query("pending orders");
+
+// With limits
+await nttp.query("top 10 products by price");
+await nttp.query("show me 5 recent orders");
+
+// Aggregations
+await nttp.query("count all users");
+await nttp.query("total revenue by category");
+await nttp.query("average order value");
+
+// Complex conditions
+await nttp.query("products with 4+ star rating under $100");
+await nttp.query("orders from California in the last 30 days");
+await nttp.query("users who joined this year");
+```
+
+## Database Support
+
+NTTP works with any SQL database supported by Knex.js:
+
+- **PostgreSQL** - Recommended for production
+- **MySQL** - Widely supported
+- **SQLite** - Perfect for development
+- **SQL Server** - Enterprise-ready
+
+## Performance
+
+- **Cache Hit**: <50ms average
+- **Cache Miss**: ~2-3s (LLM call)
+- **Throughput**: >10,000 req/s (cached)
+
+## Error Handling
+
+```typescript
+import { IntentParseError, SQLGenerationError, SQLExecutionError } from 'nttp';
+
+try {
+  const result = await nttp.query("ambiguous query");
+} catch (error) {
+  if (error instanceof IntentParseError) {
+    console.error('Could not understand query');
+  } else if (error instanceof SQLGenerationError) {
+    console.error('Could not generate SQL');
+  } else if (error instanceof SQLExecutionError) {
+    console.error('SQL execution failed');
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  NTTPConfig,
+  QueryResult,
+  Intent,
+  SchemaDefinition,
+  CacheStats
+} from 'nttp';
+```
+
+## License
+
+MIT

package/dist/NTTP.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Main nttp class - provides programmatic API for natural language database queries.
+ */
+import type { NTTPConfig, QueryOptions, QueryResult, Intent, SchemaDefinition, CacheStats } from './types.js';
+/**
+ * nttp - natural text to query
+ *
+ * @example
+ * ```typescript
+ * const nttp = new NTTP({
+ *   database: {
+ *     client: 'pg',
+ *     connection: process.env.DATABASE_URL
+ *   },
+ *   llm: {
+ *     provider: 'anthropic',
+ *     model: 'claude-sonnet-4-5-20250929',
+ *     apiKey: process.env.ANTHROPIC_API_KEY
+ *   },
+ *   cache: {
+ *     l2: {
+ *       provider: 'openai',
+ *       model: 'text-embedding-3-small',
+ *       apiKey: process.env.OPENAI_API_KEY
+ *     }
+ *   }
+ * });
+ *
+ * const users = await nttp.query("get all active users");
+ * ```
+ */
+export declare class NTTP {
+    private config;
+    private db;
+    private inspector;
+    private cache;
+    private llm;
+    private intentParser;
+    private executor;
+    private schemaInfo;
+    private l1Cache?;
+    private l2Cache?;
+    constructor(config: NTTPConfig);
+    /**
+     * Initialize NTTP - must be called before using.
+     */
+    init(): Promise<void>;
+    /**
+     * Execute a natural language query.
+     *
+     * @example
+     * ```typescript
+     * const result = await nttp.query("get top 10 products by price");
+     * console.log(result.data); // Array of products
+     * ```
+     */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Explain what SQL would be generated without executing.
+     *
+     * @example
+     * ```typescript
+     * const explanation = await nttp.explain("show pending orders");
+     * console.log(explanation.sql); // Generated SQL
+     * console.log(explanation.intent); // Parsed intent
+     * ```
+     */
+    explain(query: string): Promise<{
+        query: string;
+        intent: Intent;
+        sql: string;
+        params: any[];
+        schemaId: string;
+        cachedSchema: SchemaDefinition | null;
+    }>;
+    /**
+     * Get all cached schemas.
+     */
+    listSchemas(): Promise<SchemaDefinition[]>;
+    /**
+     * Get a specific cached schema.
+     */
+    getSchema(schemaId: string): Promise<SchemaDefinition | undefined>;
+    /**
+     * Delete a cached schema.
+     */
+    deleteSchema(schemaId: string): Promise<void>;
+    /**
+     * Pin a schema to prevent eviction.
+     */
+    pinSchema(schemaId: string): Promise<void>;
+    /**
+     * Unpin a schema.
+     */
+    unpinSchema(schemaId: string): Promise<void>;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): Promise<CacheStats>;
+    /**
+     * Get list of all database tables.
+     */
+    getTables(): Promise<string[]>;
+    /**
+     * Get schema for a specific table.
+     */
+    getTableSchema(tableName: string): Promise<any[]>;
+    /**
+     * Get formatted schema description for LLM prompts.
+     */
+    getSchemaDescription(): string;
+    /**
+     * Close database connection and cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Build schema information cache.
+     */
+    private buildSchemaInfo;
+}
+//# sourceMappingURL=NTTP.d.ts.map

package/dist/NTTP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NTTP.d.ts","sourceRoot":"","sources":["../src/NTTP.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,gBAAgB,EAChB,UAAU,EACX,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,IAAI;IAaH,OAAO,CAAC,MAAM;IAZ1B,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,UAAU,CAAkE;IAGpF,OAAO,CAAC,OAAO,CAAC,CAAa;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAgB;gBAEZ,MAAM,EAAE,UAAU;IA8BtC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;OAQG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoB5E;;;;;;;;;OASG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QACpC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,GAAG,EAAE,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;KACvC,CAAC;IAkBF;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIhD;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAIxE;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IA4B1C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpC;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAIvD;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAW9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;YACW,eAAe;CAW9B"}

package/dist/NTTP.js

@@ -0,0 +1,229 @@
+/**
+ * Main nttp class - provides programmatic API for natural language database queries.
+ */
+import { knex } from 'knex';
+import { SchemaInspector } from 'knex-schema-inspector';
+import { SchemaCache } from './cache.js';
+import { LLMService } from './llm.js';
+import { IntentParser } from './intent.js';
+import { QueryExecutor } from './executor.js';
+import { ExactCache, SemanticCache } from './cache/index.js';
+/**
+ * nttp - natural text to query
+ *
+ * @example
+ * ```typescript
+ * const nttp = new NTTP({
+ *   database: {
+ *     client: 'pg',
+ *     connection: process.env.DATABASE_URL
+ *   },
+ *   llm: {
+ *     provider: 'anthropic',
+ *     model: 'claude-sonnet-4-5-20250929',
+ *     apiKey: process.env.ANTHROPIC_API_KEY
+ *   },
+ *   cache: {
+ *     l2: {
+ *       provider: 'openai',
+ *       model: 'text-embedding-3-small',
+ *       apiKey: process.env.OPENAI_API_KEY
+ *     }
+ *   }
+ * });
+ *
+ * const users = await nttp.query("get all active users");
+ * ```
+ */
+export class NTTP {
+    config;
+    db;
+    inspector;
+    cache;
+    llm;
+    intentParser;
+    executor;
+    schemaInfo = {};
+    // 3-layer caches
+    l1Cache;
+    l2Cache;
+    constructor(config) {
+        this.config = config;
+        // Initialize Knex
+        this.db = knex(config.database);
+        // Initialize schema inspector
+        this.inspector = SchemaInspector(this.db);
+        // Initialize services
+        this.cache = new SchemaCache();
+        this.llm = new LLMService(config.llm);
+        this.intentParser = new IntentParser(this.llm);
+        // Initialize 3-layer caches
+        if (config.cache?.l1?.enabled !== false) {
+            this.l1Cache = new ExactCache(config.cache?.l1?.maxSize);
+        }
+        if (config.cache?.l2?.enabled !== false && config.cache?.l2) {
+            this.l2Cache = new SemanticCache(config.cache.l2);
+        }
+        // Initialize executor with caches
+        this.executor = new QueryExecutor(this.db, this.llm, this.cache, this.l1Cache, this.l2Cache);
+    }
+    /**
+     * Initialize NTTP - must be called before using.
+     */
+    async init() {
+        // Test database connection
+        await this.db.raw('SELECT 1');
+        // Build schema cache
+        await this.buildSchemaInfo();
+    }
+    /**
+     * Execute a natural language query.
+     *
+     * @example
+     * ```typescript
+     * const result = await nttp.query("get top 10 products by price");
+     * console.log(result.data); // Array of products
+     * ```
+     */
+    async query(query, options = {}) {
+        const startTime = Date.now();
+        // Parse intent from natural language
+        const intent = await this.intentParser.parse(query, this.getSchemaDescription());
+        // Execute query with caching
+        const result = await this.executor.execute({
+            query,
+            intent,
+            useCache: options.useCache ?? true,
+            forceNewSchema: options.forceNewSchema ?? false,
+        });
+        return {
+            ...result,
+            executionTimeMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Explain what SQL would be generated without executing.
+     *
+     * @example
+     * ```typescript
+     * const explanation = await nttp.explain("show pending orders");
+     * console.log(explanation.sql); // Generated SQL
+     * console.log(explanation.intent); // Parsed intent
+     * ```
+     */
+    async explain(query) {
+        const intent = await this.intentParser.parse(query, this.getSchemaDescription());
+        const schemaId = this.intentParser.generateSchemaId(intent);
+        const cached = await this.cache.get(schemaId);
+        // Generate SQL without executing
+        const { sql, params } = await this.executor.generateSql(intent);
+        return {
+            query,
+            intent,
+            sql,
+            params,
+            schemaId,
+            cachedSchema: cached || null,
+        };
+    }
+    /**
+     * Get all cached schemas.
+     */
+    async listSchemas() {
+        return this.cache.listAll();
+    }
+    /**
+     * Get a specific cached schema.
+     */
+    async getSchema(schemaId) {
+        return this.cache.get(schemaId);
+    }
+    /**
+     * Delete a cached schema.
+     */
+    async deleteSchema(schemaId) {
+        await this.cache.delete(schemaId);
+    }
+    /**
+     * Pin a schema to prevent eviction.
+     */
+    async pinSchema(schemaId) {
+        await this.cache.pin(schemaId);
+    }
+    /**
+     * Unpin a schema.
+     */
+    async unpinSchema(schemaId) {
+        await this.cache.unpin(schemaId);
+    }
+    /**
+     * Get cache statistics.
+     */
+    async getCacheStats() {
+        const l1Stats = this.l1Cache?.getStats() ?? { size: 0, hits: 0, misses: 0 };
+        const l2Stats = this.l2Cache?.getStats() ?? { size: 0, hits: 0, misses: 0 };
+        const totalQueries = l1Stats.hits + l1Stats.misses;
+        const l1Hits = l1Stats.hits;
+        const l2Hits = l2Stats.hits;
+        const l3Calls = l2Stats.misses;
+        // Calculate cost savings
+        // L1 saves $0.01 per hit
+        // L2 saves $0.01 - $0.0001 = $0.0099 per hit
+        const estimatedCostSaved = l1Hits * 0.01 + l2Hits * 0.0099;
+        return {
+            l1: l1Stats,
+            l2: l2Stats,
+            l3: { calls: l3Calls },
+            totalQueries,
+            hitRates: {
+                l1: totalQueries > 0 ? l1Hits / totalQueries : 0,
+                l2: totalQueries > 0 ? l2Hits / totalQueries : 0,
+                l3: totalQueries > 0 ? l3Calls / totalQueries : 0,
+            },
+            estimatedCostSaved,
+        };
+    }
+    /**
+     * Get list of all database tables.
+     */
+    async getTables() {
+        return this.inspector.tables();
+    }
+    /**
+     * Get schema for a specific table.
+     */
+    async getTableSchema(tableName) {
+        return this.inspector.columnInfo(tableName);
+    }
+    /**
+     * Get formatted schema description for LLM prompts.
+     */
+    getSchemaDescription() {
+        const lines = [`Database schema (${this.config.database.client}):`];
+        for (const [table, info] of Object.entries(this.schemaInfo)) {
+            const columns = info.columns.join(', ');
+            lines.push(`- ${table} (${columns})`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Close database connection and cleanup.
+     */
+    async close() {
+        await this.db.destroy();
+    }
+    /**
+     * Build schema information cache.
+     */
+    async buildSchemaInfo() {
+        const tables = await this.getTables();
+        for (const table of tables) {
+            const columns = await this.inspector.columnInfo(table);
+            this.schemaInfo[table] = {
+                columns: columns.map((col) => col.name),
+                description: `Table: ${table}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=NTTP.js.map

package/dist/NTTP.js.map

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

package/dist/cache/exact-cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * L1 Exact Match Cache
+ * Fast hash-based cache for identical queries
+ */
+import type { CachedResult, LayerStats } from './types.js';
+/**
+ * L1 exact match cache using Map with LRU eviction
+ */
+export declare class ExactCache {
+    private cache;
+    private accessOrder;
+    private accessCounter;
+    private maxSize;
+    private hits;
+    private misses;
+    constructor(maxSize?: number);
+    /**
+     * Get cached result for a query
+     */
+    get(query: string): CachedResult | null;
+    /**
+     * Set cached result for a query
+     */
+    set(query: string, result: CachedResult): void;
+    /**
+     * Clear all cached results
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): LayerStats;
+    /**
+     * Normalize query string for consistent cache keys
+     * - Convert to lowercase
+     * - Trim whitespace
+     * - Collapse multiple spaces
+     * - Hash to fixed-length key
+     */
+    private normalizeQuery;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+}
+//# sourceMappingURL=exact-cache.d.ts.map

package/dist/cache/exact-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-cache.d.ts","sourceRoot":"","sources":["../../src/cache/exact-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,GAAE,MAAa;IAIlC;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAiBvC;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAY9C;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,QAAQ,IAAI,UAAU;IAQtB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAatB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAgBjB"}