@mastra/couchbase 0.0.2-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+export { DISTANCE_MAPPING } from './_tsup-dts-rollup.cjs';
+export { CouchbaseVector } from './_tsup-dts-rollup.cjs';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DISTANCE_MAPPING } from './_tsup-dts-rollup.js';
+export { CouchbaseVector } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -0,0 +1,240 @@
+import { MastraVector } from '@mastra/core/vector';
+import { connect, SearchRequest, VectorSearch, VectorQuery } from 'couchbase';
+
+// src/vector/index.ts
+var DISTANCE_MAPPING = {
+  cosine: "cosine",
+  euclidean: "l2_norm",
+  dotproduct: "dot_product"
+};
+var CouchbaseVector = class extends MastraVector {
+  clusterPromise;
+  cluster;
+  bucketName;
+  collectionName;
+  scopeName;
+  collection;
+  bucket;
+  scope;
+  vector_dimension;
+  constructor(cnn_string, username, password, bucketName, scopeName, collectionName) {
+    super();
+    const baseClusterPromise = connect(cnn_string, {
+      username,
+      password,
+      configProfile: "wanDevelopment"
+    });
+    const telemetry = this.__getTelemetry();
+    this.clusterPromise = telemetry?.traceClass(baseClusterPromise, {
+      spanNamePrefix: "couchbase-vector",
+      attributes: {
+        "vector.type": "couchbase"
+      }
+    }) ?? baseClusterPromise;
+    this.cluster = null;
+    this.bucketName = bucketName;
+    this.collectionName = collectionName;
+    this.scopeName = scopeName;
+    this.collection = null;
+    this.bucket = null;
+    this.scope = null;
+    this.vector_dimension = null;
+  }
+  async getCollection() {
+    if (!this.cluster) {
+      this.cluster = await this.clusterPromise;
+    }
+    if (!this.collection) {
+      this.bucket = this.cluster.bucket(this.bucketName);
+      this.scope = this.bucket.scope(this.scopeName);
+      this.collection = this.scope.collection(this.collectionName);
+    }
+    return this.collection;
+  }
+  async createIndex(params) {
+    const { indexName, dimension, metric = "dotproduct" } = params;
+    await this.getCollection();
+    if (!Number.isInteger(dimension) || dimension <= 0) {
+      throw new Error("Dimension must be a positive integer");
+    }
+    await this.scope.searchIndexes().upsertIndex({
+      name: indexName,
+      sourceName: this.bucketName,
+      type: "fulltext-index",
+      params: {
+        doc_config: {
+          docid_prefix_delim: "",
+          docid_regexp: "",
+          mode: "scope.collection.type_field",
+          type_field: "type"
+        },
+        mapping: {
+          default_analyzer: "standard",
+          default_datetime_parser: "dateTimeOptional",
+          default_field: "_all",
+          default_mapping: {
+            dynamic: true,
+            enabled: false
+          },
+          default_type: "_default",
+          docvalues_dynamic: true,
+          // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
+          index_dynamic: true,
+          store_dynamic: true,
+          // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
+          type_field: "_type",
+          types: {
+            [`${this.scopeName}.${this.collectionName}`]: {
+              dynamic: true,
+              enabled: true,
+              properties: {
+                embedding: {
+                  enabled: true,
+                  fields: [
+                    {
+                      dims: dimension,
+                      index: true,
+                      name: "embedding",
+                      similarity: DISTANCE_MAPPING[metric],
+                      type: "vector",
+                      vector_index_optimized_for: "recall",
+                      store: true,
+                      // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                      docvalues: true,
+                      // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                      include_term_vectors: true
+                      // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                    }
+                  ]
+                },
+                content: {
+                  enabled: true,
+                  fields: [
+                    {
+                      index: true,
+                      name: "content",
+                      store: true,
+                      type: "text"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        store: {
+          indexType: "scorch",
+          segmentVersion: 16
+        }
+      },
+      sourceUuid: "",
+      sourceParams: {},
+      sourceType: "gocbcore",
+      planParams: {
+        maxPartitionsPerPIndex: 64,
+        indexPartitions: 16,
+        numReplicas: 0
+      }
+    });
+    this.vector_dimension = dimension;
+  }
+  async upsert(params) {
+    const { vectors, metadata, ids } = params;
+    await this.getCollection();
+    if (!vectors || vectors.length === 0) {
+      throw new Error("No vectors provided");
+    }
+    if (this.vector_dimension) {
+      for (const vector of vectors) {
+        if (!vector || this.vector_dimension !== vector.length) {
+          throw new Error("Vector dimension mismatch");
+        }
+      }
+    }
+    const pointIds = ids || vectors.map(() => crypto.randomUUID());
+    const records = vectors.map((vector, i) => {
+      const metadataObj = metadata?.[i] || {};
+      const record = {
+        embedding: vector,
+        metadata: metadataObj
+      };
+      if (metadataObj.text) {
+        record.content = metadataObj.text;
+      }
+      return record;
+    });
+    const allPromises = [];
+    for (let i = 0; i < records.length; i++) {
+      allPromises.push(this.collection.upsert(pointIds[i], records[i]));
+    }
+    await Promise.all(allPromises);
+    return pointIds;
+  }
+  async query(params) {
+    const { indexName, queryVector, topK = 10, includeVector = false } = params;
+    await this.getCollection();
+    const index_stats = await this.describeIndex(indexName);
+    if (queryVector.length !== index_stats.dimension) {
+      throw new Error(`Query vector dimension mismatch. Expected ${index_stats.dimension}, got ${queryVector.length}`);
+    }
+    let request = SearchRequest.create(
+      VectorSearch.fromVectorQuery(VectorQuery.create("embedding", queryVector).numCandidates(topK))
+    );
+    const results = await this.scope.search(indexName, request, {
+      fields: ["*"]
+    });
+    if (includeVector) {
+      throw new Error("Including vectors in search results is not yet supported by the Couchbase vector store");
+    }
+    const output = [];
+    for (const match of results.rows) {
+      const cleanedMetadata = {};
+      const fields = match.fields || {};
+      for (const key in fields) {
+        if (Object.prototype.hasOwnProperty.call(fields, key)) {
+          const newKey = key.startsWith("metadata.") ? key.substring("metadata.".length) : key;
+          cleanedMetadata[newKey] = fields[key];
+        }
+      }
+      output.push({
+        id: match.id,
+        score: match.score || 0,
+        metadata: cleanedMetadata
+        // Use the cleaned metadata object
+      });
+    }
+    return output;
+  }
+  async listIndexes() {
+    await this.getCollection();
+    const indexes = await this.scope.searchIndexes().getAllIndexes();
+    return indexes?.map((index) => index.name) || [];
+  }
+  async describeIndex(indexName) {
+    await this.getCollection();
+    if (!(await this.listIndexes()).includes(indexName)) {
+      throw new Error(`Index ${indexName} does not exist`);
+    }
+    const index = await this.scope.searchIndexes().getIndex(indexName);
+    const dimensions = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.dims;
+    const count = -1;
+    const metric = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.similarity;
+    return {
+      dimension: dimensions,
+      count,
+      metric: Object.keys(DISTANCE_MAPPING).find(
+        (key) => DISTANCE_MAPPING[key] === metric
+      )
+    };
+  }
+  async deleteIndex(indexName) {
+    await this.getCollection();
+    if (!(await this.listIndexes()).includes(indexName)) {
+      throw new Error(`Index ${indexName} does not exist`);
+    }
+    await this.scope.searchIndexes().dropIndex(indexName);
+    this.vector_dimension = null;
+  }
+};
+
+export { CouchbaseVector, DISTANCE_MAPPING };

package/docker-compose.yaml

@@ -0,0 +1,21 @@
+services:
+  mastra_couchbase_testing:
+    image: couchbase:enterprise-7.6.4
+    ports:
+      - "8091-8095:8091-8095"
+      - "11210:11210"
+      - "9102:9102"
+    expose:
+      - "8091"
+      - "8092"
+      - "8093"
+      - "8094"
+      - "8095"
+      - "9102"
+      - "11210"
+    healthcheck: # checks couchbase server is up
+      test: ["CMD", "curl", "-v", "http://localhost:8091/pools"]
+      interval: 20s
+      timeout: 20s
+      retries: 5
+    container_name: mastra_couchbase_testing

package/eslint.config.js

@@ -0,0 +1,6 @@
+import { createConfig } from '@internal/lint/eslint';
+
+const config = await createConfig();
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [...config];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mastra/couchbase",
+  "version": "0.0.2-alpha.0",
+  "description": "Couchbase vector store provider for Mastra",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "couchbase": "^4.4.5",
+    "@mastra/core": "^0.9.2-alpha.5"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.52.1",
+    "@types/node": "^20.17.27",
+    "@vitest/coverage-v8": "3.0.9",
+    "@vitest/ui": "3.0.9",
+    "axios": "^1.8.4",
+    "eslint": "^9.23.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9",
+    "@internal/lint": "0.0.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",
+    "build:watch": "pnpm build --watch",
+    "lint": "eslint .",
+    "coverage": "vitest run --coverage",
+    "pretest": "node scripts/start-docker.js",
+    "test": "vitest run",
+    "posttest": "node scripts/stop-docker.js"
+  }
+}

package/scripts/start-docker.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+try {
+  execSync('docker compose -f "./docker-compose.yaml" ps --quiet');
+  console.log('Container already running, bringing it down first...');
+  execSync('docker compose -f "./docker-compose.yaml" down --volumes', { stdio: 'inherit' });
+} catch (error) {
+  console.error('No existing container found', error);
+}
+try {
+  execSync('docker compose -f "./docker-compose.yaml" up --wait', { stdio: 'inherit' });
+} catch (error) {
+  console.error('Failed to start container', error);
+}

package/scripts/stop-docker.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+try {
+  execSync('docker compose -f "./docker-compose.yaml" down --volumes', { stdio: 'inherit' });
+} catch (error) {
+  console.error('Failed to stop container', error);
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './vector';