@mastra/libsql 0.0.1-alpha.1

package/dist/index.js

@@ -0,0 +1,1139 @@
+import { createClient } from '@libsql/client';
+import { MastraVector } from '@mastra/core/vector';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import { MastraStorage, TABLE_WORKFLOW_SNAPSHOT, TABLE_THREADS, TABLE_MESSAGES, TABLE_EVALS, TABLE_TRACES } from '@mastra/core/storage';
+
+// src/vector/index.ts
+var LibSQLFilterTranslator = class extends BaseFilterTranslator {
+  getSupportedOperators() {
+    return {
+      ...BaseFilterTranslator.DEFAULT_OPERATORS,
+      regex: [],
+      custom: ["$contains", "$size"]
+    };
+  }
+  translate(filter) {
+    if (this.isEmpty(filter)) {
+      return filter;
+    }
+    this.validateFilter(filter);
+    return this.translateNode(filter);
+  }
+  translateNode(node, currentPath = "") {
+    if (this.isRegex(node)) {
+      throw new Error("Direct regex pattern format is not supported in LibSQL");
+    }
+    const withPath = (result2) => currentPath ? { [currentPath]: result2 } : result2;
+    if (this.isPrimitive(node)) {
+      return withPath({ $eq: this.normalizeComparisonValue(node) });
+    }
+    if (Array.isArray(node)) {
+      return withPath({ $in: this.normalizeArrayValues(node) });
+    }
+    const entries = Object.entries(node);
+    const result = {};
+    for (const [key, value] of entries) {
+      const newPath = currentPath ? `${currentPath}.${key}` : key;
+      if (this.isLogicalOperator(key)) {
+        result[key] = Array.isArray(value) ? value.map((filter) => this.translateNode(filter)) : this.translateNode(value);
+      } else if (this.isOperator(key)) {
+        if (this.isArrayOperator(key) && !Array.isArray(value) && key !== "$elemMatch") {
+          result[key] = [value];
+        } else if (this.isBasicOperator(key) && Array.isArray(value)) {
+          result[key] = JSON.stringify(value);
+        } else {
+          result[key] = value;
+        }
+      } else if (typeof value === "object" && value !== null) {
+        const hasOperators = Object.keys(value).some((k) => this.isOperator(k));
+        if (hasOperators) {
+          result[newPath] = this.translateNode(value);
+        } else {
+          Object.assign(result, this.translateNode(value, newPath));
+        }
+      } else {
+        result[newPath] = this.translateNode(value);
+      }
+    }
+    return result;
+  }
+  // TODO: Look more into regex support for LibSQL
+  // private translateRegexPattern(pattern: string, options: string = ''): any {
+  //   if (!options) return { $regex: pattern };
+  //   const flags = options
+  //     .split('')
+  //     .filter(f => 'imsux'.includes(f))
+  //     .join('');
+  //   return {
+  //     $regex: pattern,
+  //     $options: flags,
+  //   };
+  // }
+};
+
+// src/vector/sql-builder.ts
+var createBasicOperator = (symbol) => {
+  return (key) => ({
+    sql: `CASE 
+      WHEN ? IS NULL THEN json_extract(metadata, '$."${handleKey(key)}"') IS ${symbol === "=" ? "" : "NOT"} NULL
+      ELSE json_extract(metadata, '$."${handleKey(key)}"') ${symbol} ?
+    END`,
+    needsValue: true,
+    transformValue: (value) => {
+      return [value, value];
+    }
+  });
+};
+var createNumericOperator = (symbol) => {
+  return (key) => ({
+    sql: `CAST(json_extract(metadata, '$."${handleKey(key)}"') AS NUMERIC) ${symbol} ?`,
+    needsValue: true
+  });
+};
+var validateJsonArray = (key) => `json_valid(json_extract(metadata, '$."${handleKey(key)}"'))
+   AND json_type(json_extract(metadata, '$."${handleKey(key)}"')) = 'array'`;
+var FILTER_OPERATORS = {
+  $eq: createBasicOperator("="),
+  $ne: createBasicOperator("!="),
+  $gt: createNumericOperator(">"),
+  $gte: createNumericOperator(">="),
+  $lt: createNumericOperator("<"),
+  $lte: createNumericOperator("<="),
+  // Array Operators
+  $in: (key, value) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') IN (${value.map(() => "?").join(",")})`,
+    needsValue: true
+  }),
+  $nin: (key, value) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') NOT IN (${value.map(() => "?").join(",")})`,
+    needsValue: true
+  }),
+  $all: (key) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') = ?`,
+    needsValue: true,
+    transformValue: (value) => {
+      const arrayValue = Array.isArray(value) ? value : [value];
+      if (arrayValue.length === 0) {
+        return {
+          sql: "1 = 0",
+          values: []
+        };
+      }
+      return {
+        sql: `(
+          CASE
+            WHEN ${validateJsonArray(key)} THEN
+                NOT EXISTS (
+                    SELECT value 
+                    FROM json_each(?) 
+                    WHERE value NOT IN (
+                    SELECT value 
+                    FROM json_each(json_extract(metadata, '$."${handleKey(key)}"'))
+                )
+            )
+            ELSE FALSE
+          END
+        )`,
+        values: [JSON.stringify(arrayValue)]
+      };
+    }
+  }),
+  $elemMatch: (key) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') = ?`,
+    needsValue: true,
+    transformValue: (value) => {
+      if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("$elemMatch requires an object with conditions");
+      }
+      const conditions = Object.entries(value).map(([field, fieldValue]) => {
+        if (field.startsWith("$")) {
+          const { sql, values } = buildCondition("elem.value", { [field]: fieldValue });
+          const pattern = /json_extract\(metadata, '\$\."[^"]*"(\."[^"]*")*'\)/g;
+          const elemSql = sql.replace(pattern, "elem.value");
+          return { sql: elemSql, values };
+        } else if (typeof fieldValue === "object" && !Array.isArray(fieldValue)) {
+          const { sql, values } = buildCondition(field, fieldValue);
+          const pattern = /json_extract\(metadata, '\$\."[^"]*"(\."[^"]*")*'\)/g;
+          const elemSql = sql.replace(pattern, `json_extract(elem.value, '$."${field}"')`);
+          return { sql: elemSql, values };
+        } else {
+          return {
+            sql: `json_extract(elem.value, '$."${field}"') = ?`,
+            values: [fieldValue]
+          };
+        }
+      });
+      return {
+        sql: `(
+          CASE
+            WHEN ${validateJsonArray(key)} THEN
+              EXISTS (
+                SELECT 1 
+                FROM json_each(json_extract(metadata, '$."${handleKey(key)}"')) as elem
+                WHERE ${conditions.map((c) => c.sql).join(" AND ")}
+              )
+            ELSE FALSE
+          END
+        )`,
+        values: conditions.flatMap((c) => c.values)
+      };
+    }
+  }),
+  // Element Operators
+  $exists: (key) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') IS NOT NULL`,
+    needsValue: false
+  }),
+  // Logical Operators
+  $and: (key) => ({
+    sql: `(${key})`,
+    needsValue: false
+  }),
+  $or: (key) => ({
+    sql: `(${key})`,
+    needsValue: false
+  }),
+  $not: (key) => ({ sql: `NOT (${key})`, needsValue: false }),
+  $nor: (key) => ({
+    sql: `NOT (${key})`,
+    needsValue: false
+  }),
+  $size: (key, paramIndex) => ({
+    sql: `(
+    CASE
+      WHEN json_type(json_extract(metadata, '$."${handleKey(key)}"')) = 'array' THEN 
+        json_array_length(json_extract(metadata, '$."${handleKey(key)}"')) = $${paramIndex}
+      ELSE FALSE
+    END
+  )`,
+    needsValue: true
+  }),
+  //   /**
+  //    * Regex Operators
+  //    * Supports case insensitive and multiline
+  //    */
+  //   $regex: (key: string): FilterOperator => ({
+  //     sql: `json_extract(metadata, '$."${handleKey(key)}"') = ?`,
+  //     needsValue: true,
+  //     transformValue: (value: any) => {
+  //       const pattern = typeof value === 'object' ? value.$regex : value;
+  //       const options = typeof value === 'object' ? value.$options || '' : '';
+  //       let sql = `json_extract(metadata, '$."${handleKey(key)}"')`;
+  //       // Handle multiline
+  //       //   if (options.includes('m')) {
+  //       //     sql = `REPLACE(${sql}, CHAR(10), '\n')`;
+  //       //   }
+  //       //       let finalPattern = pattern;
+  //       // if (options) {
+  //       //   finalPattern = `(\\?${options})${pattern}`;
+  //       // }
+  //       //   // Handle case insensitivity
+  //       //   if (options.includes('i')) {
+  //       //     sql = `LOWER(${sql}) REGEXP LOWER(?)`;
+  //       //   } else {
+  //       //     sql = `${sql} REGEXP ?`;
+  //       //   }
+  //       if (options.includes('m')) {
+  //         sql = `EXISTS (
+  //         SELECT 1
+  //         FROM json_each(
+  //           json_array(
+  //             ${sql},
+  //             REPLACE(${sql}, CHAR(10), CHAR(13))
+  //           )
+  //         ) as lines
+  //         WHERE lines.value REGEXP ?
+  //       )`;
+  //       } else {
+  //         sql = `${sql} REGEXP ?`;
+  //       }
+  //       // Handle case insensitivity
+  //       if (options.includes('i')) {
+  //         sql = sql.replace('REGEXP ?', 'REGEXP LOWER(?)');
+  //         sql = sql.replace('value REGEXP', 'LOWER(value) REGEXP');
+  //       }
+  //       // Handle extended - allows whitespace and comments in pattern
+  //       if (options.includes('x')) {
+  //         // Remove whitespace and comments from pattern
+  //         const cleanPattern = pattern.replace(/\s+|#.*$/gm, '');
+  //         return {
+  //           sql,
+  //           values: [cleanPattern],
+  //         };
+  //       }
+  //       return {
+  //         sql,
+  //         values: [pattern],
+  //       };
+  //     },
+  //   }),
+  $contains: (key) => ({
+    sql: `json_extract(metadata, '$."${handleKey(key)}"') = ?`,
+    needsValue: true,
+    transformValue: (value) => {
+      if (Array.isArray(value)) {
+        return {
+          sql: `(
+            SELECT ${validateJsonArray(key)}
+            AND EXISTS (
+              SELECT 1 
+              FROM json_each(json_extract(metadata, '$."${handleKey(key)}"')) as m
+              WHERE m.value IN (SELECT value FROM json_each(?))
+            )
+          )`,
+          values: [JSON.stringify(value)]
+        };
+      }
+      if (value && typeof value === "object") {
+        let traverse2 = function(obj, path = []) {
+          for (const [k, v] of Object.entries(obj)) {
+            const currentPath = [...path, k];
+            if (v && typeof v === "object" && !Array.isArray(v)) {
+              traverse2(v, currentPath);
+            } else {
+              paths.push(currentPath.join("."));
+              values.push(v);
+            }
+          }
+        };
+        const paths = [];
+        const values = [];
+        traverse2(value);
+        return {
+          sql: `(${paths.map((path) => `json_extract(metadata, '$."${handleKey(key)}"."${path}"') = ?`).join(" AND ")})`,
+          values
+        };
+      }
+      return value;
+    }
+  })
+};
+var handleKey = (key) => {
+  return key.replace(/\./g, '"."');
+};
+function buildFilterQuery(filter) {
+  if (!filter) {
+    return { sql: "", values: [] };
+  }
+  const values = [];
+  const conditions = Object.entries(filter).map(([key, value]) => {
+    const condition = buildCondition(key, value);
+    values.push(...condition.values);
+    return condition.sql;
+  }).join(" AND ");
+  return {
+    sql: conditions ? `WHERE ${conditions}` : "",
+    values
+  };
+}
+function buildCondition(key, value, parentPath) {
+  if (["$and", "$or", "$not", "$nor"].includes(key)) {
+    return handleLogicalOperator(key, value);
+  }
+  if (!value || typeof value !== "object") {
+    return {
+      sql: `json_extract(metadata, '$."${key.replace(/\./g, '"."')}"') = ?`,
+      values: [value]
+    };
+  }
+  return handleOperator(key, value);
+}
+function handleLogicalOperator(key, value, parentPath) {
+  if (!value || value.length === 0) {
+    switch (key) {
+      case "$and":
+      case "$nor":
+        return { sql: "true", values: [] };
+      case "$or":
+        return { sql: "false", values: [] };
+      case "$not":
+        throw new Error("$not operator cannot be empty");
+      default:
+        return { sql: "true", values: [] };
+    }
+  }
+  if (key === "$not") {
+    const entries = Object.entries(value);
+    const conditions2 = entries.map(([fieldKey, fieldValue]) => buildCondition(fieldKey, fieldValue));
+    return {
+      sql: `NOT (${conditions2.map((c) => c.sql).join(" AND ")})`,
+      values: conditions2.flatMap((c) => c.values)
+    };
+  }
+  const values = [];
+  const joinOperator = key === "$or" || key === "$nor" ? "OR" : "AND";
+  const conditions = Array.isArray(value) ? value.map((f) => {
+    const entries = Object.entries(f);
+    return entries.map(([k, v]) => buildCondition(k, v));
+  }) : [buildCondition(key, value)];
+  const joined = conditions.flat().map((c) => {
+    values.push(...c.values);
+    return c.sql;
+  }).join(` ${joinOperator} `);
+  return {
+    sql: key === "$nor" ? `NOT (${joined})` : `(${joined})`,
+    values
+  };
+}
+function handleOperator(key, value) {
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const entries = Object.entries(value);
+    const results = entries.map(
+      ([operator2, operatorValue2]) => operator2 === "$not" ? {
+        sql: `NOT (${Object.entries(operatorValue2).map(([op, val]) => processOperator(key, op, val).sql).join(" AND ")})`,
+        values: Object.entries(operatorValue2).flatMap(
+          ([op, val]) => processOperator(key, op, val).values
+        )
+      } : processOperator(key, operator2, operatorValue2)
+    );
+    return {
+      sql: `(${results.map((r) => r.sql).join(" AND ")})`,
+      values: results.flatMap((r) => r.values)
+    };
+  }
+  const [[operator, operatorValue] = []] = Object.entries(value);
+  return processOperator(key, operator, operatorValue);
+}
+var processOperator = (key, operator, operatorValue) => {
+  if (!operator.startsWith("$") || !FILTER_OPERATORS[operator]) {
+    throw new Error(`Invalid operator: ${operator}`);
+  }
+  const operatorFn = FILTER_OPERATORS[operator];
+  const operatorResult = operatorFn(key, operatorValue);
+  if (!operatorResult.needsValue) {
+    return { sql: operatorResult.sql, values: [] };
+  }
+  const transformed = operatorResult.transformValue ? operatorResult.transformValue(operatorValue) : operatorValue;
+  if (transformed && typeof transformed === "object" && "sql" in transformed) {
+    return transformed;
+  }
+  return {
+    sql: operatorResult.sql,
+    values: Array.isArray(transformed) ? transformed : [transformed]
+  };
+};
+
+// src/vector/index.ts
+var LibSQLVector = class extends MastraVector {
+  turso;
+  constructor({
+    connectionUrl,
+    authToken,
+    syncUrl,
+    syncInterval
+  }) {
+    super();
+    this.turso = createClient({
+      url: connectionUrl,
+      syncUrl,
+      authToken,
+      syncInterval
+    });
+    if (connectionUrl.includes(`file:`) || connectionUrl.includes(`:memory:`)) {
+      void this.turso.execute({
+        sql: "PRAGMA journal_mode=WAL;",
+        args: {}
+      });
+    }
+  }
+  transformFilter(filter) {
+    const translator = new LibSQLFilterTranslator();
+    return translator.translate(filter);
+  }
+  async query(...args) {
+    const params = this.normalizeArgs("query", args, ["minScore"]);
+    try {
+      const { indexName, queryVector, topK = 10, filter, includeVector = false, minScore = 0 } = params;
+      const vectorStr = `[${queryVector.join(",")}]`;
+      const translatedFilter = this.transformFilter(filter);
+      const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter);
+      filterValues.push(minScore);
+      const query = `
+        WITH vector_scores AS (
+          SELECT
+            vector_id as id,
+            (1-vector_distance_cos(embedding, '${vectorStr}')) as score,
+            metadata
+            ${includeVector ? ", vector_extract(embedding) as embedding" : ""}
+          FROM ${indexName}
+          ${filterQuery}
+        )
+        SELECT *
+        FROM vector_scores
+        WHERE score > ?
+        ORDER BY score DESC
+        LIMIT ${topK}`;
+      const result = await this.turso.execute({
+        sql: query,
+        args: filterValues
+      });
+      return result.rows.map(({ id, score, metadata, embedding }) => ({
+        id,
+        score,
+        metadata: JSON.parse(metadata ?? "{}"),
+        ...includeVector && embedding && { vector: JSON.parse(embedding) }
+      }));
+    } finally {
+    }
+  }
+  async upsert(...args) {
+    const params = this.normalizeArgs("upsert", args);
+    const { indexName, vectors, metadata, ids } = params;
+    const tx = await this.turso.transaction("write");
+    try {
+      const vectorIds = ids || vectors.map(() => crypto.randomUUID());
+      for (let i = 0; i < vectors.length; i++) {
+        const query = `
+          INSERT INTO ${indexName} (vector_id, embedding, metadata)
+          VALUES (?, vector32(?), ?)
+          ON CONFLICT(vector_id) DO UPDATE SET
+            embedding = vector32(?),
+            metadata = ?
+        `;
+        await tx.execute({
+          sql: query,
+          // @ts-ignore
+          args: [
+            vectorIds[i],
+            JSON.stringify(vectors[i]),
+            JSON.stringify(metadata?.[i] || {}),
+            JSON.stringify(vectors[i]),
+            JSON.stringify(metadata?.[i] || {})
+          ]
+        });
+      }
+      await tx.commit();
+      return vectorIds;
+    } catch (error) {
+      await tx.rollback();
+      if (error instanceof Error && error.message?.includes("dimensions are different")) {
+        const match = error.message.match(/dimensions are different: (\d+) != (\d+)/);
+        if (match) {
+          const [, actual, expected] = match;
+          throw new Error(
+            `Vector dimension mismatch: Index "${indexName}" expects ${expected} dimensions but got ${actual} dimensions. Either use a matching embedding model or delete and recreate the index with the new dimension.`
+          );
+        }
+      }
+      throw error;
+    }
+  }
+  async createIndex(...args) {
+    const params = this.normalizeArgs("createIndex", args);
+    const { indexName, dimension } = params;
+    try {
+      if (!indexName.match(/^[a-zA-Z_][a-zA-Z0-9_]*$/)) {
+        throw new Error("Invalid index name format");
+      }
+      if (!Number.isInteger(dimension) || dimension <= 0) {
+        throw new Error("Dimension must be a positive integer");
+      }
+      await this.turso.execute({
+        sql: `
+        CREATE TABLE IF NOT EXISTS ${indexName} (
+          id SERIAL PRIMARY KEY,
+          vector_id TEXT UNIQUE NOT NULL,
+          embedding F32_BLOB(${dimension}),
+          metadata TEXT DEFAULT '{}'
+        );
+      `,
+        args: []
+      });
+      await this.turso.execute({
+        sql: `
+        CREATE INDEX IF NOT EXISTS ${indexName}_vector_idx
+        ON ${indexName} (libsql_vector_idx(embedding))
+      `,
+        args: []
+      });
+    } catch (error) {
+      console.error("Failed to create vector table:", error);
+      throw error;
+    } finally {
+    }
+  }
+  async deleteIndex(indexName) {
+    try {
+      await this.turso.execute({
+        sql: `DROP TABLE IF EXISTS ${indexName}`,
+        args: []
+      });
+    } catch (error) {
+      console.error("Failed to delete vector table:", error);
+      throw new Error(`Failed to delete vector table: ${error.message}`);
+    } finally {
+    }
+  }
+  async listIndexes() {
+    try {
+      const vectorTablesQuery = `
+        SELECT name FROM sqlite_master 
+        WHERE type='table' 
+        AND sql LIKE '%F32_BLOB%';
+      `;
+      const result = await this.turso.execute({
+        sql: vectorTablesQuery,
+        args: []
+      });
+      return result.rows.map((row) => row.name);
+    } catch (error) {
+      throw new Error(`Failed to list vector tables: ${error.message}`);
+    }
+  }
+  async describeIndex(indexName) {
+    try {
+      const tableInfoQuery = `
+        SELECT sql 
+        FROM sqlite_master 
+        WHERE type='table' 
+        AND name = ?;
+      `;
+      const tableInfo = await this.turso.execute({
+        sql: tableInfoQuery,
+        args: [indexName]
+      });
+      if (!tableInfo.rows[0]?.sql) {
+        throw new Error(`Table ${indexName} not found`);
+      }
+      const dimension = parseInt(tableInfo.rows[0].sql.match(/F32_BLOB\((\d+)\)/)?.[1] || "0");
+      const countQuery = `
+        SELECT COUNT(*) as count
+        FROM ${indexName};
+      `;
+      const countResult = await this.turso.execute({
+        sql: countQuery,
+        args: []
+      });
+      const metric = "cosine";
+      return {
+        dimension,
+        count: countResult?.rows?.[0]?.count ?? 0,
+        metric
+      };
+    } catch (e) {
+      throw new Error(`Failed to describe vector table: ${e.message}`);
+    }
+  }
+  /**
+   * Updates an index entry by its ID with the provided vector and/or metadata.
+   *
+   * @param indexName - The name of the index to update.
+   * @param id - The ID of the index entry to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
+  async updateIndexById(indexName, id, update) {
+    try {
+      const updates = [];
+      const args = [];
+      if (update.vector) {
+        updates.push("embedding = vector32(?)");
+        args.push(JSON.stringify(update.vector));
+      }
+      if (update.metadata) {
+        updates.push("metadata = ?");
+        args.push(JSON.stringify(update.metadata));
+      }
+      if (updates.length === 0) {
+        throw new Error("No updates provided");
+      }
+      args.push(id);
+      const query = `
+        UPDATE ${indexName}
+        SET ${updates.join(", ")}
+        WHERE vector_id = ?;
+      `;
+      await this.turso.execute({
+        sql: query,
+        args
+      });
+    } catch (error) {
+      throw new Error(`Failed to update index by id: ${id} for index: ${indexName}: ${error.message}`);
+    }
+  }
+  async deleteIndexById(indexName, id) {
+    try {
+      await this.turso.execute({
+        sql: `DELETE FROM ${indexName} WHERE vector_id = ?`,
+        args: [id]
+      });
+    } catch (error) {
+      throw new Error(`Failed to delete index by id: ${id} for index: ${indexName}: ${error.message}`);
+    }
+  }
+  async truncateIndex(indexName) {
+    await this.turso.execute({
+      sql: `DELETE FROM ${indexName}`,
+      args: []
+    });
+  }
+};
+function safelyParseJSON(jsonString) {
+  try {
+    return JSON.parse(jsonString);
+  } catch {
+    return {};
+  }
+}
+var LibSQLStore = class extends MastraStorage {
+  client;
+  constructor(config) {
+    super({ name: `LibSQLStore` });
+    if (config.url.endsWith(":memory:")) {
+      this.shouldCacheInit = false;
+    }
+    this.client = createClient(config);
+  }
+  getCreateTableSQL(tableName, schema) {
+    const columns = Object.entries(schema).map(([name, col]) => {
+      let type = col.type.toUpperCase();
+      if (type === "TEXT") type = "TEXT";
+      if (type === "TIMESTAMP") type = "TEXT";
+      const nullable = col.nullable ? "" : "NOT NULL";
+      const primaryKey = col.primaryKey ? "PRIMARY KEY" : "";
+      return `${name} ${type} ${nullable} ${primaryKey}`.trim();
+    });
+    if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
+      const stmnt = `CREATE TABLE IF NOT EXISTS ${tableName} (
+                ${columns.join(",\n")},
+                PRIMARY KEY (workflow_name, run_id)
+            )`;
+      return stmnt;
+    }
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (${columns.join(", ")})`;
+  }
+  async createTable({
+    tableName,
+    schema
+  }) {
+    try {
+      this.logger.debug(`Creating database table`, { tableName, operation: "schema init" });
+      const sql = this.getCreateTableSQL(tableName, schema);
+      await this.client.execute(sql);
+    } catch (error) {
+      this.logger.error(`Error creating table ${tableName}: ${error}`);
+      throw error;
+    }
+  }
+  async clearTable({ tableName }) {
+    try {
+      await this.client.execute(`DELETE FROM ${tableName}`);
+    } catch (e) {
+      if (e instanceof Error) {
+        this.logger.error(e.message);
+      }
+    }
+  }
+  prepareStatement({ tableName, record }) {
+    const columns = Object.keys(record);
+    const values = Object.values(record).map((v) => {
+      if (typeof v === `undefined`) {
+        return null;
+      }
+      if (v instanceof Date) {
+        return v.toISOString();
+      }
+      return typeof v === "object" ? JSON.stringify(v) : v;
+    });
+    const placeholders = values.map(() => "?").join(", ");
+    return {
+      sql: `INSERT OR REPLACE INTO ${tableName} (${columns.join(", ")}) VALUES (${placeholders})`,
+      args: values
+    };
+  }
+  async insert({ tableName, record }) {
+    try {
+      await this.client.execute(
+        this.prepareStatement({
+          tableName,
+          record
+        })
+      );
+    } catch (error) {
+      this.logger.error(`Error upserting into table ${tableName}: ${error}`);
+      throw error;
+    }
+  }
+  async batchInsert({ tableName, records }) {
+    if (records.length === 0) return;
+    try {
+      const batchStatements = records.map((r) => this.prepareStatement({ tableName, record: r }));
+      await this.client.batch(batchStatements, "write");
+    } catch (error) {
+      this.logger.error(`Error upserting into table ${tableName}: ${error}`);
+      throw error;
+    }
+  }
+  async load({ tableName, keys }) {
+    const conditions = Object.entries(keys).map(([key]) => `${key} = ?`).join(" AND ");
+    const values = Object.values(keys);
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${tableName} WHERE ${conditions} ORDER BY createdAt DESC LIMIT 1`,
+      args: values
+    });
+    if (!result.rows || result.rows.length === 0) {
+      return null;
+    }
+    const row = result.rows[0];
+    const parsed = Object.fromEntries(
+      Object.entries(row || {}).map(([k, v]) => {
+        try {
+          return [k, typeof v === "string" ? v.startsWith("{") || v.startsWith("[") ? JSON.parse(v) : v : v];
+        } catch {
+          return [k, v];
+        }
+      })
+    );
+    return parsed;
+  }
+  async getThreadById({ threadId }) {
+    const result = await this.load({
+      tableName: TABLE_THREADS,
+      keys: { id: threadId }
+    });
+    if (!result) {
+      return null;
+    }
+    return {
+      ...result,
+      metadata: typeof result.metadata === "string" ? JSON.parse(result.metadata) : result.metadata
+    };
+  }
+  async getThreadsByResourceId({ resourceId }) {
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${TABLE_THREADS} WHERE resourceId = ?`,
+      args: [resourceId]
+    });
+    if (!result.rows) {
+      return [];
+    }
+    return result.rows.map((thread) => ({
+      id: thread.id,
+      resourceId: thread.resourceId,
+      title: thread.title,
+      createdAt: thread.createdAt,
+      updatedAt: thread.updatedAt,
+      metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata
+    }));
+  }
+  async saveThread({ thread }) {
+    await this.insert({
+      tableName: TABLE_THREADS,
+      record: {
+        ...thread,
+        metadata: JSON.stringify(thread.metadata)
+      }
+    });
+    return thread;
+  }
+  async updateThread({
+    id,
+    title,
+    metadata
+  }) {
+    const thread = await this.getThreadById({ threadId: id });
+    if (!thread) {
+      throw new Error(`Thread ${id} not found`);
+    }
+    const updatedThread = {
+      ...thread,
+      title,
+      metadata: {
+        ...thread.metadata,
+        ...metadata
+      }
+    };
+    await this.client.execute({
+      sql: `UPDATE ${TABLE_THREADS} SET title = ?, metadata = ? WHERE id = ?`,
+      args: [title, JSON.stringify(updatedThread.metadata), id]
+    });
+    return updatedThread;
+  }
+  async deleteThread({ threadId }) {
+    await this.client.execute({
+      sql: `DELETE FROM ${TABLE_THREADS} WHERE id = ?`,
+      args: [threadId]
+    });
+  }
+  parseRow(row) {
+    let content = row.content;
+    try {
+      content = JSON.parse(row.content);
+    } catch {
+    }
+    return {
+      id: row.id,
+      content,
+      role: row.role,
+      type: row.type,
+      createdAt: new Date(row.createdAt),
+      threadId: row.thread_id
+    };
+  }
+  async getMessages({ threadId, selectBy }) {
+    try {
+      const messages = [];
+      const limit = typeof selectBy?.last === `number` ? selectBy.last : 40;
+      if (selectBy?.include?.length) {
+        const includeIds = selectBy.include.map((i) => i.id);
+        const maxPrev = Math.max(...selectBy.include.map((i) => i.withPreviousMessages || 0));
+        const maxNext = Math.max(...selectBy.include.map((i) => i.withNextMessages || 0));
+        const includeResult = await this.client.execute({
+          sql: `
+            WITH numbered_messages AS (
+              SELECT 
+                id,
+                content,
+                role,
+                type,
+                "createdAt",
+                thread_id,
+                ROW_NUMBER() OVER (ORDER BY "createdAt" ASC) as row_num
+              FROM "${TABLE_MESSAGES}"
+              WHERE thread_id = ?
+            ),
+            target_positions AS (
+              SELECT row_num as target_pos
+              FROM numbered_messages
+              WHERE id IN (${includeIds.map(() => "?").join(", ")})
+            )
+            SELECT DISTINCT m.*
+            FROM numbered_messages m
+            CROSS JOIN target_positions t
+            WHERE m.row_num BETWEEN (t.target_pos - ?) AND (t.target_pos + ?)
+            ORDER BY m."createdAt" ASC
+          `,
+          args: [threadId, ...includeIds, maxPrev, maxNext]
+        });
+        if (includeResult.rows) {
+          messages.push(...includeResult.rows.map((row) => this.parseRow(row)));
+        }
+      }
+      const excludeIds = messages.map((m) => m.id);
+      const remainingSql = `
+        SELECT 
+          id, 
+          content, 
+          role, 
+          type,
+          "createdAt", 
+          thread_id
+        FROM "${TABLE_MESSAGES}"
+        WHERE thread_id = ?
+        ${excludeIds.length ? `AND id NOT IN (${excludeIds.map(() => "?").join(", ")})` : ""}
+        ORDER BY "createdAt" DESC
+        LIMIT ?
+      `;
+      const remainingArgs = [threadId, ...excludeIds.length ? excludeIds : [], limit];
+      const remainingResult = await this.client.execute({
+        sql: remainingSql,
+        args: remainingArgs
+      });
+      if (remainingResult.rows) {
+        messages.push(...remainingResult.rows.map((row) => this.parseRow(row)));
+      }
+      messages.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+      return messages;
+    } catch (error) {
+      this.logger.error("Error getting messages:", error);
+      throw error;
+    }
+  }
+  async saveMessages({ messages }) {
+    if (messages.length === 0) return messages;
+    try {
+      const threadId = messages[0]?.threadId;
+      if (!threadId) {
+        throw new Error("Thread ID is required");
+      }
+      const batchStatements = messages.map((message) => {
+        const time = message.createdAt || /* @__PURE__ */ new Date();
+        return {
+          sql: `INSERT INTO ${TABLE_MESSAGES} (id, thread_id, content, role, type, createdAt) 
+                VALUES (?, ?, ?, ?, ?, ?)`,
+          args: [
+            message.id,
+            threadId,
+            typeof message.content === "object" ? JSON.stringify(message.content) : message.content,
+            message.role,
+            message.type,
+            time instanceof Date ? time.toISOString() : time
+          ]
+        };
+      });
+      await this.client.batch(batchStatements, "write");
+      return messages;
+    } catch (error) {
+      this.logger.error("Failed to save messages in database: " + error?.message);
+      throw error;
+    }
+  }
+  transformEvalRow(row) {
+    const resultValue = JSON.parse(row.result);
+    const testInfoValue = row.test_info ? JSON.parse(row.test_info) : void 0;
+    if (!resultValue || typeof resultValue !== "object" || !("score" in resultValue)) {
+      throw new Error(`Invalid MetricResult format: ${JSON.stringify(resultValue)}`);
+    }
+    return {
+      input: row.input,
+      output: row.output,
+      result: resultValue,
+      agentName: row.agent_name,
+      metricName: row.metric_name,
+      instructions: row.instructions,
+      testInfo: testInfoValue,
+      globalRunId: row.global_run_id,
+      runId: row.run_id,
+      createdAt: row.created_at
+    };
+  }
+  async getEvalsByAgentName(agentName, type) {
+    try {
+      const baseQuery = `SELECT * FROM ${TABLE_EVALS} WHERE agent_name = ?`;
+      const typeCondition = type === "test" ? " AND test_info IS NOT NULL AND test_info->>'testPath' IS NOT NULL" : type === "live" ? " AND (test_info IS NULL OR test_info->>'testPath' IS NULL)" : "";
+      const result = await this.client.execute({
+        sql: `${baseQuery}${typeCondition} ORDER BY created_at DESC`,
+        args: [agentName]
+      });
+      return result.rows?.map((row) => this.transformEvalRow(row)) ?? [];
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("no such table")) {
+        return [];
+      }
+      this.logger.error("Failed to get evals for the specified agent: " + error?.message);
+      throw error;
+    }
+  }
+  // TODO: add types
+  async getTraces({
+    name,
+    scope,
+    page,
+    perPage,
+    attributes,
+    filters
+  } = {
+    page: 0,
+    perPage: 100
+  }) {
+    const limit = perPage;
+    const offset = page * perPage;
+    const args = [];
+    const conditions = [];
+    if (name) {
+      conditions.push("name LIKE CONCAT(?, '%')");
+    }
+    if (scope) {
+      conditions.push("scope = ?");
+    }
+    if (attributes) {
+      Object.keys(attributes).forEach((key) => {
+        conditions.push(`attributes->>'$.${key}' = ?`);
+      });
+    }
+    if (filters) {
+      Object.entries(filters).forEach(([key, _value]) => {
+        conditions.push(`${key} = ?`);
+      });
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    if (name) {
+      args.push(name);
+    }
+    if (scope) {
+      args.push(scope);
+    }
+    if (attributes) {
+      for (const [, value] of Object.entries(attributes)) {
+        args.push(value);
+      }
+    }
+    if (filters) {
+      for (const [, value] of Object.entries(filters)) {
+        args.push(value);
+      }
+    }
+    args.push(limit, offset);
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${TABLE_TRACES} ${whereClause} ORDER BY "startTime" DESC LIMIT ? OFFSET ?`,
+      args
+    });
+    if (!result.rows) {
+      return [];
+    }
+    return result.rows.map((row) => ({
+      id: row.id,
+      parentSpanId: row.parentSpanId,
+      traceId: row.traceId,
+      name: row.name,
+      scope: row.scope,
+      kind: row.kind,
+      status: safelyParseJSON(row.status),
+      events: safelyParseJSON(row.events),
+      links: safelyParseJSON(row.links),
+      attributes: safelyParseJSON(row.attributes),
+      startTime: row.startTime,
+      endTime: row.endTime,
+      other: safelyParseJSON(row.other),
+      createdAt: row.createdAt
+    }));
+  }
+  async getWorkflowRuns({
+    workflowName,
+    fromDate,
+    toDate,
+    limit,
+    offset
+  } = {}) {
+    const conditions = [];
+    const args = [];
+    if (workflowName) {
+      conditions.push("workflow_name = ?");
+      args.push(workflowName);
+    }
+    if (fromDate) {
+      conditions.push("createdAt >= ?");
+      args.push(fromDate.toISOString());
+    }
+    if (toDate) {
+      conditions.push("createdAt <= ?");
+      args.push(toDate.toISOString());
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    let total = 0;
+    if (limit !== void 0 && offset !== void 0) {
+      const countResult = await this.client.execute({
+        sql: `SELECT COUNT(*) as count FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+        args
+      });
+      total = Number(countResult.rows?.[0]?.count ?? 0);
+    }
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== void 0 && offset !== void 0 ? ` LIMIT ? OFFSET ?` : ""}`,
+      args: limit !== void 0 && offset !== void 0 ? [...args, limit, offset] : args
+    });
+    const runs = (result.rows || []).map((row) => {
+      let parsedSnapshot = row.snapshot;
+      if (typeof parsedSnapshot === "string") {
+        try {
+          parsedSnapshot = JSON.parse(row.snapshot);
+        } catch (e) {
+          console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+        }
+      }
+      return {
+        workflowName: row.workflow_name,
+        runId: row.run_id,
+        snapshot: parsedSnapshot,
+        createdAt: new Date(row.createdAt),
+        updatedAt: new Date(row.updatedAt)
+      };
+    });
+    return { runs, total: total || runs.length };
+  }
+};
+
+export { LibSQLStore as DefaultStorage, LibSQLStore, LibSQLVector };