@databridgeai/toolkit 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# @databridgeai/toolkit
+
+**Schema introspection, playground helpers, and utility functions for DataBridge AI.**
+
+This package provides lower-level tools for advanced integrations. Most users should use `@databridgeai/connector` instead.
+
+## Installation
+
+```bash
+npm install @databridgeai/toolkit
+```
+
+## Schema Introspection
+
+Automatically discover your database schema:
+
+### PostgreSQL
+
+```typescript
+import { introspectPostgres } from '@databridgeai/toolkit';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const schema = await introspectPostgres(pool, {
+  tables: ['users', 'orders', 'products'],
+  tenantField: 'organization_id',
+});
+
+console.log(schema);
+// {
+//   tables: [
+//     { name: 'users', columns: [{ name: 'id', type: 'integer' }, ...] },
+//     { name: 'orders', columns: [...] },
+//   ]
+// }
+```
+
+### MongoDB
+
+```typescript
+import { introspectMongo } from '@databridgeai/toolkit';
+import { MongoClient } from 'mongodb';
+
+const client = new MongoClient(process.env.MONGO_URL!);
+const db = client.db('myapp');
+
+const schema = await introspectMongo(db, {
+  collections: ['users', 'orders'],
+});
+```
+
+## Agent (Full Runtime Integration)
+
+For direct runtime API integration without the connector:
+
+```typescript
+import { initAgent } from '@databridgeai/toolkit';
+
+const agent = initAgent({
+  apiKey: process.env.DATABRIDGE_API_KEY!,
+  db: pool,
+  exposeTables: ['users', 'orders'],
+  runtimeUrl: 'https://your-server.vercel.app',
+});
+
+await agent.init();
+const result = await agent.chat('Show top customers', userContext);
+```
+
+## Playground HTML
+
+Generate a self-contained chat playground UI:
+
+```typescript
+import { getPlaygroundHTML } from '@databridgeai/toolkit';
+
+app.get('/playground', (_req, res) => {
+  res.setHeader('Content-Type', 'text/html');
+  res.send(getPlaygroundHTML());
+});
+```
+
+## Exports
+
+| Export | Description |
+|--------|------------|
+| `introspectPostgres()` | Discover Postgres table schemas |
+| `introspectMongo()` | Discover MongoDB collection schemas |
+| `initAgent()` | Create an agent with full runtime integration |
+| `getPlaygroundHTML()` | Generate chat playground HTML |
+
+## Related Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@databridgeai/connector` | Recommended backend connector |
+| `@databridgeai/react` | React chat widget |
+| `@databridgeai/core` | Shared types & validators |
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,70 @@
+import { Pool } from "pg";
+import { Db } from "mongodb";
+import { UserContext } from "@databridgeai/core";
+export interface AgentConfig {
+    /** API key for authenticating with the runtime */
+    apiKey: string;
+    /** Database connection — Postgres Pool or Mongo Db instance */
+    db: Pool | Db;
+    /** Tables/collections to expose to the AI agent */
+    exposeTables: string[];
+    /** Field used for tenant isolation (e.g., "org_id") */
+    tenantField?: string;
+    /** Runtime server URL (defaults to http://localhost:3100) */
+    runtimeUrl?: string;
+}
+export declare class AgentClient {
+    private config;
+    private projectId;
+    private runtimeUrl;
+    constructor(config: AgentConfig);
+    /**
+     * Initialize the agent: introspect DB schema and register with runtime.
+     */
+    init(): Promise<{
+        projectId: string;
+    }>;
+    /**
+     * Send a chat message to the AI agent.
+     */
+    chat(message: string, userContext: UserContext): Promise<{
+        message: string;
+        data?: any;
+    }>;
+    /**
+     * Returns an Express-compatible middleware that proxies chat requests.
+     * Mount it on your app: app.post('/ai/chat', agent.middleware())
+     */
+    middleware(): (req: any, res: any) => Promise<void>;
+    /**
+     * Returns Express middleware to serve the embedded Chat Playground UI.
+     * Mount it on your app: app.get('/playground', agent.playgroundUI())
+     *
+     * This provides a ready-to-use web interface for testing the AI agent.
+     */
+    playgroundUI(options?: {
+        chatEndpoint?: string;
+        defaultUserId?: string;
+        defaultOrgId?: string;
+        defaultRole?: string;
+        projectName?: string;
+    }): (_req: any, res: any) => void;
+    private getDbType;
+    private introspectSchema;
+    private getConnectionString;
+}
+/**
+ * Create and initialize an agent.
+ *
+ * Usage:
+ * ```ts
+ * const agent = await initAgent({
+ *   apiKey: process.env.AGENT_KEY!,
+ *   db: pool, // pg Pool or mongo Db
+ *   exposeTables: ["users", "orders"],
+ *   tenantField: "org_id"
+ * });
+ * ```
+ */
+export declare function initAgent(config: AgentConfig): Promise<AgentClient>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EAAe,EAAE,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAA+B,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAO9E,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,+DAA+D;IAC/D,EAAE,EAAE,IAAI,GAAG,EAAE,CAAC;IAEd,mDAAmD;IACnD,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,WAAW;IAK/B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA0C5C;;OAEG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IAgC3C;;;OAGG;IACH,UAAU,KACM,KAAK,GAAG,EAAE,KAAK,GAAG;IAyBlC;;;;;OAKG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,IASS,MAAM,GAAG,EAAE,KAAK,GAAG;IAgB7B,OAAO,CAAC,SAAS;YAaH,gBAAgB;IAgB9B,OAAO,CAAC,mBAAmB;CA+B5B;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CAItB"}

package/dist/agent.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+exports.initAgent = initAgent;
+const pg_1 = require("pg");
+const introspect_postgres_1 = require("./introspect-postgres");
+const introspect_mongo_1 = require("./introspect-mongo");
+const playground_1 = require("./playground");
+// ─── Agent Client ─────────────────────────────────────────
+class AgentClient {
+    config;
+    projectId = null;
+    runtimeUrl;
+    constructor(config) {
+        this.config = config;
+        this.runtimeUrl = config.runtimeUrl || "http://localhost:3100";
+    }
+    /**
+     * Initialize the agent: introspect DB schema and register with runtime.
+     */
+    async init() {
+        console.log("[databridgeai/toolkit] Initializing agent...");
+        // 1. Detect DB type and introspect
+        const schema = await this.introspectSchema();
+        console.log(`[databridgeai/toolkit] Introspected ${schema.tables.length} table(s).`);
+        // 2. Detect connection string for runtime to use
+        const connectionString = this.getConnectionString();
+        // 3. Register with runtime
+        const response = await fetch(`${this.runtimeUrl}/register-project`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                apiKey: this.config.apiKey,
+                dbType: this.getDbType(),
+                schema,
+                tenantField: this.config.tenantField,
+                connectionString,
+            }),
+        });
+        if (!response.ok) {
+            const err = await response.json().catch(() => ({}));
+            throw new Error(`Failed to register with runtime: ${response.status} ${JSON.stringify(err)}`);
+        }
+        const result = (await response.json());
+        this.projectId = result.projectId;
+        console.log(`[databridgeai/toolkit] Registered as project "${this.projectId}".`);
+        return result;
+    }
+    /**
+     * Send a chat message to the AI agent.
+     */
+    async chat(message, userContext) {
+        if (!this.projectId) {
+            throw new Error("Agent not initialized. Call init() before chat().");
+        }
+        const body = {
+            projectId: this.projectId,
+            message,
+            userContext,
+        };
+        const response = await fetch(`${this.runtimeUrl}/chat`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.config.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const err = await response.json().catch(() => ({}));
+            throw new Error(`Chat request failed: ${response.status} ${JSON.stringify(err)}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Returns an Express-compatible middleware that proxies chat requests.
+     * Mount it on your app: app.post('/ai/chat', agent.middleware())
+     */
+    middleware() {
+        return async (req, res) => {
+            try {
+                const { message, userContext } = req.body;
+                if (!message) {
+                    res.status(400).json({ error: "Missing 'message' in request body." });
+                    return;
+                }
+                if (!userContext?.orgId) {
+                    res
+                        .status(400)
+                        .json({ error: "Missing 'userContext.orgId' in request body." });
+                    return;
+                }
+                const result = await this.chat(message, userContext);
+                res.json(result);
+            }
+            catch (err) {
+                console.error("[databridgeai/toolkit] Middleware error:", err);
+                res.status(500).json({ error: err.message });
+            }
+        };
+    }
+    /**
+     * Returns Express middleware to serve the embedded Chat Playground UI.
+     * Mount it on your app: app.get('/playground', agent.playgroundUI())
+     *
+     * This provides a ready-to-use web interface for testing the AI agent.
+     */
+    playgroundUI(options) {
+        const { chatEndpoint = '/ai/chat', defaultUserId = 'user_1', defaultOrgId = 'org_acme', defaultRole = 'admin', projectName = 'AI Agent', } = options || {};
+        return (_req, res) => {
+            res.setHeader('Content-Type', 'text/html');
+            res.send((0, playground_1.getPlaygroundHTML)({
+                chatEndpoint,
+                defaultUserId,
+                defaultOrgId,
+                defaultRole,
+                projectName,
+            }));
+        };
+    }
+    // ─── Private methods ──────────────────────────────────
+    getDbType() {
+        if (this.config.db instanceof pg_1.Pool)
+            return "postgres";
+        // Check if it's a Mongo Db instance
+        if (this.config.db &&
+            typeof this.config.db.collection === "function" &&
+            typeof this.config.db.databaseName === "string") {
+            return "mongo";
+        }
+        throw new Error("Unable to detect database type from provided db instance.");
+    }
+    async introspectSchema() {
+        const dbType = this.getDbType();
+        if (dbType === "postgres") {
+            return (0, introspect_postgres_1.introspectPostgres)(this.config.db, this.config.exposeTables);
+        }
+        else {
+            return (0, introspect_mongo_1.introspectMongo)(this.config.db, this.config.exposeTables);
+        }
+    }
+    getConnectionString() {
+        const dbType = this.getDbType();
+        if (dbType === "postgres") {
+            const pool = this.config.db;
+            // Extract connection string from pool options
+            const opts = pool.options;
+            if (opts?.connectionString)
+                return opts.connectionString;
+            // Build from individual options
+            const host = opts?.host || "localhost";
+            const port = opts?.port || 5432;
+            const database = opts?.database || "postgres";
+            const user = opts?.user || "postgres";
+            const password = opts?.password || "";
+            return `postgresql://${user}:${password}@${host}:${port}/${database}`;
+        }
+        else {
+            // For Mongo, the connection string is typically in the client
+            const db = this.config.db;
+            const client = db.client;
+            // Try extracting from MongoClient
+            if (client?.options) {
+                const hosts = client.s?.options?.hosts;
+                const dbName = db.databaseName;
+                if (hosts && hosts.length > 0) {
+                    return `mongodb://${hosts[0]}/${dbName}`;
+                }
+            }
+            return `mongodb://localhost:27017/${db.databaseName}`;
+        }
+    }
+}
+exports.AgentClient = AgentClient;
+// ─── Convenience function ─────────────────────────────────
+/**
+ * Create and initialize an agent.
+ *
+ * Usage:
+ * ```ts
+ * const agent = await initAgent({
+ *   apiKey: process.env.AGENT_KEY!,
+ *   db: pool, // pg Pool or mongo Db
+ *   exposeTables: ["users", "orders"],
+ *   tenantField: "org_id"
+ * });
+ * ```
+ */
+async function initAgent(config) {
+    const client = new AgentClient(config);
+    await client.init();
+    return client;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AgentClient, initAgent } from "./agent";
+export type { AgentConfig } from "./agent";
+export { introspectPostgres } from "./introspect-postgres";
+export { introspectMongo } from "./introspect-mongo";
+export { getPlaygroundHTML } from "./playground";
+//# 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":"AAGA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// ─── @databridgeai/toolkit ────────────────────────────────────────────
+// Customer-facing SDK for AI Agent integration.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlaygroundHTML = exports.introspectMongo = exports.introspectPostgres = exports.initAgent = exports.AgentClient = void 0;
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "AgentClient", { enumerable: true, get: function () { return agent_1.AgentClient; } });
+Object.defineProperty(exports, "initAgent", { enumerable: true, get: function () { return agent_1.initAgent; } });
+var introspect_postgres_1 = require("./introspect-postgres");
+Object.defineProperty(exports, "introspectPostgres", { enumerable: true, get: function () { return introspect_postgres_1.introspectPostgres; } });
+var introspect_mongo_1 = require("./introspect-mongo");
+Object.defineProperty(exports, "introspectMongo", { enumerable: true, get: function () { return introspect_mongo_1.introspectMongo; } });
+var playground_1 = require("./playground");
+Object.defineProperty(exports, "getPlaygroundHTML", { enumerable: true, get: function () { return playground_1.getPlaygroundHTML; } });
+//# 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,yEAAyE;AACzE,gDAAgD;;;AAEhD,iCAAiD;AAAxC,oGAAA,WAAW,OAAA;AAAE,kGAAA,SAAS,OAAA;AAE/B,6DAA2D;AAAlD,yHAAA,kBAAkB,OAAA;AAC3B,uDAAqD;AAA5C,mHAAA,eAAe,OAAA;AACxB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA"}

package/dist/introspect-mongo.d.ts

@@ -0,0 +1,8 @@
+import { Db } from "mongodb";
+import { SchemaMetadata } from "@databridgeai/core";
+/**
+ * Introspects a MongoDB database by sampling documents from each collection
+ * to infer field names and types.
+ */
+export declare function introspectMongo(db: Db, exposeCollections: string[]): Promise<SchemaMetadata>;
+//# sourceMappingURL=introspect-mongo.d.ts.map

package/dist/introspect-mongo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect-mongo.d.ts","sourceRoot":"","sources":["../src/introspect-mongo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,EAAE,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EACL,cAAc,EAGf,MAAM,oBAAoB,CAAC;AAE5B;;;GAGG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,iBAAiB,EAAE,MAAM,EAAE,GAC1B,OAAO,CAAC,cAAc,CAAC,CA0DzB"}

package/dist/introspect-mongo.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectMongo = introspectMongo;
+/**
+ * Introspects a MongoDB database by sampling documents from each collection
+ * to infer field names and types.
+ */
+async function introspectMongo(db, exposeCollections) {
+    const tables = [];
+    for (const collectionName of exposeCollections) {
+        const collection = db.collection(collectionName);
+        // Sample up to 100 documents to infer schema
+        const sampleDocs = await collection
+            .find({})
+            .limit(100)
+            .toArray();
+        if (sampleDocs.length === 0) {
+            console.warn(`[sdk] Warning: collection "${collectionName}" is empty. Adding with no fields.`);
+            tables.push({ name: collectionName, fields: [] });
+            continue;
+        }
+        // Build a union of all field names and their most common types
+        const fieldTypeMap = new Map();
+        for (const doc of sampleDocs) {
+            for (const [key, value] of Object.entries(doc)) {
+                if (key === "_id")
+                    continue; // Skip _id by default
+                if (!fieldTypeMap.has(key)) {
+                    fieldTypeMap.set(key, new Map());
+                }
+                const typeCount = fieldTypeMap.get(key);
+                const jsType = inferMongoFieldType(value);
+                typeCount.set(jsType, (typeCount.get(jsType) || 0) + 1);
+            }
+        }
+        const fields = [];
+        for (const [fieldName, typeCounts] of fieldTypeMap) {
+            // Pick the most common type
+            let maxType = "string";
+            let maxCount = 0;
+            for (const [type, count] of typeCounts) {
+                if (count > maxCount) {
+                    maxType = type;
+                    maxCount = count;
+                }
+            }
+            fields.push({ name: fieldName, type: maxType });
+        }
+        // MongoDB doesn't have native foreign keys, so relations are empty
+        tables.push({
+            name: collectionName,
+            fields,
+        });
+    }
+    return { tables };
+}
+function inferMongoFieldType(value) {
+    if (value === null || value === undefined)
+        return "string";
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? "integer" : "number";
+    }
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "string")
+        return "string";
+    if (value instanceof Date)
+        return "date";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "object")
+        return "object";
+    return "string";
+}
+//# sourceMappingURL=introspect-mongo.js.map

package/dist/introspect-mongo.js.map

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

package/dist/introspect-postgres.d.ts

@@ -0,0 +1,8 @@
+import { Pool } from "pg";
+import { SchemaMetadata } from "@databridgeai/core";
+/**
+ * Introspects a PostgreSQL database using information_schema to extract
+ * table names, column names/types, and foreign key relationships.
+ */
+export declare function introspectPostgres(pool: Pool, exposeTables: string[]): Promise<SchemaMetadata>;
+//# sourceMappingURL=introspect-postgres.d.ts.map

package/dist/introspect-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect-postgres.d.ts","sourceRoot":"","sources":["../src/introspect-postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EACL,cAAc,EAIf,MAAM,oBAAoB,CAAC;AAE5B;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,cAAc,CAAC,CA6DzB"}

package/dist/introspect-postgres.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectPostgres = introspectPostgres;
+/**
+ * Introspects a PostgreSQL database using information_schema to extract
+ * table names, column names/types, and foreign key relationships.
+ */
+async function introspectPostgres(pool, exposeTables) {
+    const tables = [];
+    for (const tableName of exposeTables) {
+        // ─── Get columns ──────────────────────────────────────
+        const colResult = await pool.query(`SELECT column_name, data_type
+       FROM information_schema.columns
+       WHERE table_name = $1
+         AND table_schema = 'public'
+       ORDER BY ordinal_position`, [tableName]);
+        if (colResult.rows.length === 0) {
+            console.warn(`[sdk] Warning: table "${tableName}" not found or has no columns.`);
+            continue;
+        }
+        const fields = colResult.rows.map((row) => ({
+            name: row.column_name,
+            type: row.data_type,
+        }));
+        // ─── Get foreign keys ─────────────────────────────────
+        const fkResult = await pool.query(`SELECT
+         kcu.column_name AS local_field,
+         ccu.table_name AS foreign_table,
+         ccu.column_name AS foreign_field
+       FROM information_schema.table_constraints AS tc
+       JOIN information_schema.key_column_usage AS kcu
+         ON tc.constraint_name = kcu.constraint_name
+         AND tc.table_schema = kcu.table_schema
+       JOIN information_schema.constraint_column_usage AS ccu
+         ON ccu.constraint_name = tc.constraint_name
+         AND ccu.table_schema = tc.table_schema
+       WHERE tc.constraint_type = 'FOREIGN KEY'
+         AND tc.table_name = $1
+         AND tc.table_schema = 'public'`, [tableName]);
+        const relations = fkResult.rows
+            .filter((row) => exposeTables.includes(row.foreign_table))
+            .map((row) => ({
+            table: row.foreign_table,
+            localField: row.local_field,
+            foreignField: row.foreign_field,
+        }));
+        tables.push({
+            name: tableName,
+            fields,
+            relations: relations.length > 0 ? relations : undefined,
+        });
+    }
+    return { tables };
+}
+//# sourceMappingURL=introspect-postgres.js.map

package/dist/introspect-postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect-postgres.js","sourceRoot":"","sources":["../src/introspect-postgres.ts"],"names":[],"mappings":";;AAYA,gDAgEC;AApED;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,YAAsB;IAEtB,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACrC,yDAAyD;QACzD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,CAChC;;;;iCAI2B,EAC3B,CAAC,SAAS,CAAC,CACZ,CAAC;QAEF,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CACV,yBAAyB,SAAS,gCAAgC,CACnE,CAAC;YACF,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAoB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC3D,IAAI,EAAE,GAAG,CAAC,WAAW;YACrB,IAAI,EAAE,GAAG,CAAC,SAAS;SACpB,CAAC,CAAC,CAAC;QAEJ,yDAAyD;QACzD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAC/B;;;;;;;;;;;;;wCAakC,EAClC,CAAC,SAAS,CAAC,CACZ,CAAC;QAEF,MAAM,SAAS,GAAuB,QAAQ,CAAC,IAAI;aAChD,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;aACzD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACb,KAAK,EAAE,GAAG,CAAC,aAAa;YACxB,UAAU,EAAE,GAAG,CAAC,WAAW;YAC3B,YAAY,EAAE,GAAG,CAAC,aAAa;SAChC,CAAC,CAAC,CAAC;QAEN,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,SAAS;YACf,MAAM;YACN,SAAS,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;SACxD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC"}

package/dist/playground.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Embedded Chat Playground for SDK users
+ *
+ * Developers can mount this in their Express apps:
+ *   app.get('/playground', agent.playgroundUI())
+ *
+ * This provides a ready-to-use chat interface for testing the AI agent.
+ */
+export declare function getPlaygroundHTML(config: {
+    chatEndpoint: string;
+    defaultUserId?: string;
+    defaultOrgId?: string;
+    defaultRole?: string;
+    projectName?: string;
+}): string;
+//# sourceMappingURL=playground.d.ts.map

package/dist/playground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAw0BT"}