sql-ai-harness 0.0.0-stage → 0.1.0

package/dist/schema/cache.js

@@ -0,0 +1,56 @@
+/**
+ * Process-local cache for database metadata. It never caches query results.
+ * A short TTL keeps repeated agent schema discovery from repeatedly hitting
+ * information_schema while allowing schema changes to become visible.
+ */
+export class SchemaCache {
+    ttlMs;
+    tables;
+    relationships;
+    tableSchemas = new Map();
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 300_000;
+    }
+    async listTables(database) {
+        const cached = this.get(this.tables);
+        if (cached)
+            return cached;
+        const value = await database.listTables();
+        this.tables = this.entry(value);
+        return value;
+    }
+    async describeTable(database, table) {
+        const key = table.toLowerCase();
+        const cached = this.get(this.tableSchemas.get(key));
+        if (cached)
+            return cached;
+        const value = await database.describeTable(table);
+        this.tableSchemas.set(key, this.entry(value));
+        return value;
+    }
+    async describeTables(database, tables) {
+        return Promise.all(tables.map((table) => this.describeTable(database, table)));
+    }
+    async getRelationships(database) {
+        const cached = this.get(this.relationships);
+        if (cached)
+            return cached;
+        const value = await database.getRelationships();
+        this.relationships = this.entry(value);
+        return value;
+    }
+    clear() {
+        this.tables = undefined;
+        this.relationships = undefined;
+        this.tableSchemas.clear();
+    }
+    entry(value) {
+        return { value, expiresAt: Date.now() + this.ttlMs };
+    }
+    get(entry) {
+        if (!entry || entry.expiresAt <= Date.now())
+            return undefined;
+        return entry.value;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/schema/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/schema/cache.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACL,KAAK,CAAS;IACvB,MAAM,CAA2B;IACjC,aAAa,CAAkC;IACtC,YAAY,GAAG,IAAI,GAAG,EAAmC,CAAC;IAE3E,YAAY,OAAO,GAAuB,EAAE;QAC1C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAyB;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,QAAyB,EAAE,KAAa;QAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,QAAyB,EAAE,MAAgB;QAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,QAAyB;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5C,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAEO,KAAK,CAAI,KAAQ;QACvB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC;IAEO,GAAG,CAAI,KAAgC;QAC7C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,SAAS,CAAC;QAC9D,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "sql-ai-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "main": "./dist/index.js",
+  "type": "module",
+  "keywords": [
+    "sql",
+    "ai",
+    "agent",
+    "database",
+    "text-to-sql",
+    "typescript"
+  ],
+  "author": "NegusDev",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.4",
+    "drizzle-kit": "1.0.0-rc.4",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "dependencies": {
+    "@ai-sdk/cerebras": "^3.0.67",
+    "@ai-sdk/google": "^4.0.93",
+    "@ai-sdk/groq": "^4.0.59",
+    "@ai-sdk/openai-compatible": "^3.0.67",
+    "@openrouter/ai-sdk-provider": "^3.1.0",
+    "ai": "^7.0.127",
+    "better-sqlite3": "^13.0.3",
+    "dotenv": "^18.0.5",
+    "drizzle-orm": "1.0.0-rc.4",
+    "hono": "^4.13.13",
+    "mysql2": "^3.24.5",
+    "zod": "^4.6.5"
+  },
+  "description": "A provider-independent TypeScript SQL AI harness for querying existing relational databases.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NegusDev/sql-ai-harness.git"
+  },
+  "homepage": "https://github.com/NegusDev/sql-ai-harness#readme",
+  "bugs": {
+    "url": "https://github.com/NegusDev/sql-ai-harness/issues"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "sql-ai-harness": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    ".env.example",
+    "sql-ai.example.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "ask": "node dist/cli.js ask",
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "eval": "tsx evals/runners/run-benchmark.ts",
+    "pack:check": "npm pack --dry-run"
+  }
 }

package/sql-ai.example.md

@@ -0,0 +1,32 @@
+# Database Context
+
+<!--
+This file is optional.
+Rename it to `sql-ai.md` if you want to provide business/domain context
+for the connected database.
+-->
+
+## Overview
+
+Describe what this database is used for and the domain it represents.
+
+Example:
+
+This database belongs to a school management system. It stores information
+about students, parents, teachers, classes, enrollments, attendance and fees.
+
+## Business Rules
+
+Add important rules that are not obvious from the database schema.
+
+- Only active enrollments represent currently enrolled students.
+- Completed payments are considered successful payments.
+- Cancelled payments should not be included in revenue calculations.
+
+## Terminology
+
+Explain domain-specific terms where the database naming may not be obvious.
+
+- Student: A learner registered at the school.
+- Enrollment: A student's registration for an academic period.
+- Revenue: The total amount from completed payments.