@larkup/vector-stores 0.1.20 → 0.1.21

package/src/registry.ts

@@ -1,4 +1,4 @@
-import type { IndexType, VectorStoreDescriptor, VectorStoreId } from "@larkup/core/types"
+import type { IndexType, VectorStoreDescriptor, VectorStoreId } from '@larkup/core/types';
 
 /**
  * Declarative registry of supported vector stores.
@@ -14,360 +14,406 @@ import type { IndexType, VectorStoreDescriptor, VectorStoreId } from "@larkup/co
  */
 export const VECTOR_STORES: Record<VectorStoreId, VectorStoreDescriptor> = {
   lancedb: {
-    id: "lancedb",
-    label: "LanceDB",
+    id: 'lancedb',
+    label: 'LanceDB',
     description:
-      "Embedded, file-based vector DB. Runs fully local for dev or against LanceDB Cloud for production.",
-    runtime: "both",
-    installStatus: "installed",
-    docsUrl: "https://lancedb.github.io/lancedb/",
+      'Embedded vector database for local development, LanceDB Cloud, or persistent S3-compatible storage such as Cloudflare R2.',
+    runtime: 'both',
+    installStatus: 'installed',
+    docsUrl: 'https://lancedb.github.io/lancedb/',
     serverDependencies: {
-      "@lancedb/lancedb": "^0.30.0",
+      '@lancedb/lancedb': '^0.30.0',
     },
     fields: [
       {
-        key: "mode",
-        label: "Mode",
-        type: "select",
+        key: 'mode',
+        label: 'Mode',
+        type: 'select',
         required: true,
-        defaultValue: "local",
-        help: "Local writes to disk on the toolkit host. Cloud connects to LanceDB Cloud.",
+        defaultValue: 'local',
+        help: 'Use a local disk, LanceDB Cloud, or an S3-compatible bucket for persistent serverless deployments.',
         options: [
-          { label: "Local (on-disk)", value: "local" },
-          { label: "Cloud", value: "cloud" },
+          { label: 'Local (on-disk)', value: 'local' },
+          { label: 'S3-compatible (Vercel / R2 / S3)', value: 's3' },
+          { label: 'Cloud', value: 'cloud' },
         ],
       },
       {
-        key: "dbPath",
-        label: "Database path",
-        type: "path",
+        key: 'dbPath',
+        label: 'Database path',
+        type: 'path',
         required: true,
-        defaultValue: "./.larkup/lancedb",
-        placeholder: "./.larkup/lancedb",
-        help: "Directory where the LanceDB tables are stored.",
-        showWhen: { key: "mode", equals: ["local"] },
+        defaultValue: './.larkup/lancedb',
+        placeholder: './.larkup/lancedb',
+        help: 'Directory where the LanceDB tables are stored.',
+        showWhen: { key: 'mode', equals: ['local'] },
       },
       {
-        key: "uri",
-        label: "Cloud URI",
-        type: "text",
+        key: 's3Uri',
+        label: 'Database URI',
+        type: 'text',
         required: true,
-        placeholder: "db://my-database",
-        help: "Your LanceDB Cloud database URI.",
-        showWhen: { key: "mode", equals: ["cloud"] },
+        placeholder: 's3://my-bucket/larkup/my-server',
+        help: 'A dedicated, private bucket prefix for LanceDB table files. This is persistent across Vercel invocations.',
+        showWhen: { key: 'mode', equals: ['s3'] },
       },
       {
-        key: "apiKey",
-        label: "API key",
-        type: "password",
+        key: 's3Endpoint',
+        label: 'S3 endpoint',
+        type: 'text',
+        required: false,
+        placeholder: 'https://<account-id>.r2.cloudflarestorage.com',
+        help: 'Required for Cloudflare R2 and other S3-compatible providers. Leave blank for AWS S3.',
+        showWhen: { key: 'mode', equals: ['s3'] },
+      },
+      {
+        key: 's3Region',
+        label: 'Region',
+        type: 'text',
+        required: true,
+        defaultValue: 'auto',
+        placeholder: 'auto',
+        help: 'Use “auto” for Cloudflare R2, or your bucket region for AWS S3.',
+        showWhen: { key: 'mode', equals: ['s3'] },
+      },
+      {
+        key: 's3AccessKeyId',
+        label: 'Access key ID',
+        type: 'password',
+        required: true,
+        secret: true,
+        help: 'Use an object read/write credential restricted to this bucket.',
+        showWhen: { key: 'mode', equals: ['s3'] },
+      },
+      {
+        key: 's3SecretAccessKey',
+        label: 'Secret access key',
+        type: 'password',
         required: true,
         secret: true,
-        placeholder: "sk_...",
-        help: "LanceDB Cloud API key. Stored as an env var in the generated server.",
-        showWhen: { key: "mode", equals: ["cloud"] },
+        help: 'Stored as a deployment environment variable; never expose it in the browser.',
+        showWhen: { key: 'mode', equals: ['s3'] },
       },
       {
-        key: "tableName",
-        label: "Table name",
-        type: "text",
+        key: 'uri',
+        label: 'Cloud URI',
+        type: 'text',
         required: true,
-        defaultValue: "documents",
-        help: "The table that holds your embedded chunks.",
+        placeholder: 'db://my-database',
+        help: 'Your LanceDB Cloud database URI.',
+        showWhen: { key: 'mode', equals: ['cloud'] },
+      },
+      {
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
+        required: true,
+        secret: true,
+        placeholder: 'sk_...',
+        help: 'LanceDB Cloud API key. Stored as an env var in the generated server.',
+        showWhen: { key: 'mode', equals: ['cloud'] },
+      },
+      {
+        key: 'tableName',
+        label: 'Table name',
+        type: 'text',
+        required: true,
+        defaultValue: 'documents',
+        help: 'The table that holds your embedded chunks.',
       },
     ],
   },
 
   pinecone: {
-    id: "pinecone",
-    label: "Pinecone",
+    id: 'pinecone',
+    label: 'Pinecone',
     description:
-      "Fully-managed cloud vector database. Cloud-only — requires an API key and an existing index.",
-    runtime: "cloud",
-    installStatus: "installed",
-    docsUrl: "https://docs.pinecone.io/",
+      'Fully-managed cloud vector database. Cloud-only — requires an API key and an existing index.',
+    runtime: 'cloud',
+    installStatus: 'installed',
+    docsUrl: 'https://docs.pinecone.io/',
     serverDependencies: {
-      "@pinecone-database/pinecone": "^6.0.0",
+      '@pinecone-database/pinecone': '^6.0.0',
     },
     fields: [
       {
-        key: "apiKey",
-        label: "API key",
-        type: "password",
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
         required: true,
         secret: true,
-        placeholder: "pcsk_...",
-        help: "Pinecone API key. Stored as an env var in the generated server.",
+        placeholder: 'pcsk_...',
+        help: 'Pinecone API key. Stored as an env var in the generated server.',
       },
       {
-        key: "indexName",
-        label: "Index name",
-        type: "text",
+        key: 'indexName',
+        label: 'Index name',
+        type: 'text',
         required: true,
-        placeholder: "rag-index",
+        placeholder: 'rag-index',
         help: "Name of the Pinecone index to upsert into / query. For hybrid/lexical mode this index must use the 'dotproduct' metric.",
       },
       {
-        key: "namespace",
-        label: "Namespace",
-        type: "text",
+        key: 'namespace',
+        label: 'Namespace',
+        type: 'text',
         required: false,
-        placeholder: "default",
-        help: "Optional namespace to isolate this dataset within the index.",
+        placeholder: 'default',
+        help: 'Optional namespace to isolate this dataset within the index.',
       },
       {
-        key: "sparseModel",
-        label: "Sparse model",
-        type: "text",
+        key: 'sparseModel',
+        label: 'Sparse model',
+        type: 'text',
         required: true,
-        defaultValue: "pinecone-sparse-english-v0",
-        help: "Pinecone-hosted sparse model used to generate keyword vectors via the Inference API. Both dense and sparse vectors are stored in the same index.",
-        showWhenIndexType: ["lexical", "hybrid"],
+        defaultValue: 'pinecone-sparse-english-v0',
+        help: 'Pinecone-hosted sparse model used to generate keyword vectors via the Inference API. Both dense and sparse vectors are stored in the same index.',
+        showWhenIndexType: ['lexical', 'hybrid'],
       },
     ],
   },
 
   weaviate: {
-    id: "weaviate",
-    label: "Weaviate",
+    id: 'weaviate',
+    label: 'Weaviate',
     description:
-      "Open-source AI-native vector database with built-in hybrid search, BM25, and multi-tenancy.",
-    runtime: "both",
-    installStatus: "coming-soon",
-    docsUrl: "https://weaviate.io/developers/weaviate",
+      'Open-source AI-native vector database with built-in hybrid search, BM25, and multi-tenancy.',
+    runtime: 'both',
+    installStatus: 'coming-soon',
+    docsUrl: 'https://weaviate.io/developers/weaviate',
     serverDependencies: {
-      weaviate: "^3.0.0",
+      weaviate: '^3.0.0',
     },
     fields: [
       {
-        key: "host",
-        label: "Host URL",
-        type: "text",
+        key: 'host',
+        label: 'Host URL',
+        type: 'text',
         required: true,
-        placeholder: "https://my-cluster.weaviate.network",
-        help: "Weaviate Cloud URL or self-hosted host address.",
+        placeholder: 'https://my-cluster.weaviate.network',
+        help: 'Weaviate Cloud URL or self-hosted host address.',
       },
       {
-        key: "apiKey",
-        label: "API key",
-        type: "password",
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
         required: false,
         secret: true,
-        placeholder: "weaviate-api-key",
-        help: "Weaviate Cloud API key (optional for self-hosted).",
+        placeholder: 'weaviate-api-key',
+        help: 'Weaviate Cloud API key (optional for self-hosted).',
       },
       {
-        key: "className",
-        label: "Collection name",
-        type: "text",
+        key: 'className',
+        label: 'Collection name',
+        type: 'text',
         required: true,
-        defaultValue: "Documents",
-        help: "The Weaviate collection (class) that holds your embedded chunks.",
+        defaultValue: 'Documents',
+        help: 'The Weaviate collection (class) that holds your embedded chunks.',
       },
     ],
   },
 
   qdrant: {
-    id: "qdrant",
-    label: "Qdrant",
+    id: 'qdrant',
+    label: 'Qdrant',
     description:
-      "High-performance vector search engine with rich filtering, built for production-scale RAG.",
-    runtime: "both",
-    installStatus: "coming-soon",
-    docsUrl: "https://qdrant.tech/documentation/",
+      'High-performance vector search engine with rich filtering, built for production-scale RAG.',
+    runtime: 'both',
+    installStatus: 'coming-soon',
+    docsUrl: 'https://qdrant.tech/documentation/',
     serverDependencies: {
-      "@qdrant/js-client-rest": "^1.9.0",
+      '@qdrant/js-client-rest': '^1.9.0',
     },
     fields: [
       {
-        key: "url",
-        label: "Host URL",
-        type: "text",
+        key: 'url',
+        label: 'Host URL',
+        type: 'text',
         required: true,
-        placeholder: "http://localhost:6333",
-        help: "Qdrant server URL (local or Qdrant Cloud endpoint).",
+        placeholder: 'http://localhost:6333',
+        help: 'Qdrant server URL (local or Qdrant Cloud endpoint).',
       },
       {
-        key: "apiKey",
-        label: "API key",
-        type: "password",
+        key: 'apiKey',
+        label: 'API key',
+        type: 'password',
         required: false,
         secret: true,
-        placeholder: "qdrant-api-key",
-        help: "Qdrant Cloud API key (leave blank for local).",
+        placeholder: 'qdrant-api-key',
+        help: 'Qdrant Cloud API key (leave blank for local).',
       },
       {
-        key: "collectionName",
-        label: "Collection name",
-        type: "text",
+        key: 'collectionName',
+        label: 'Collection name',
+        type: 'text',
         required: true,
-        defaultValue: "documents",
-        help: "Qdrant collection to upsert into and query.",
+        defaultValue: 'documents',
+        help: 'Qdrant collection to upsert into and query.',
       },
     ],
   },
 
   chroma: {
-    id: "chroma",
-    label: "Chroma",
+    id: 'chroma',
+    label: 'Chroma',
     description:
-      "Open-source, developer-friendly embedding database. Great for rapid local prototyping.",
-    runtime: "both",
-    installStatus: "installable",
-    docsUrl: "https://docs.trychroma.com/",
+      'Open-source, developer-friendly embedding database. Great for rapid local prototyping.',
+    runtime: 'both',
+    installStatus: 'installable',
+    docsUrl: 'https://docs.trychroma.com/',
     serverDependencies: {
-      chromadb: "^1.9.0",
+      chromadb: '^1.9.0',
     },
     fields: [
       {
-        key: "mode",
-        label: "Mode",
-        type: "select",
+        key: 'mode',
+        label: 'Mode',
+        type: 'select',
         required: true,
-        defaultValue: "server",
-        help: "Server connects to a self-hosted Chroma instance. Cloud connects to Chroma Cloud.",
+        defaultValue: 'server',
+        help: 'Server connects to a self-hosted Chroma instance. Cloud connects to Chroma Cloud.',
         options: [
-          { label: "Server (Self-hosted)", value: "server" },
-          { label: "Cloud (Chroma Cloud)", value: "cloud" },
+          { label: 'Server (Self-hosted)', value: 'server' },
+          { label: 'Cloud (Chroma Cloud)', value: 'cloud' },
         ],
       },
       {
-        key: "host",
-        label: "Server URL",
-        type: "text",
+        key: 'host',
+        label: 'Server URL',
+        type: 'text',
         required: true,
-        placeholder: "http://localhost:8000",
-        defaultValue: "http://localhost:8000",
-        help: "Chroma server URL (local Docker or remote).",
-        showWhen: { key: "mode", equals: ["server"] },
+        placeholder: 'http://localhost:8000',
+        defaultValue: 'http://localhost:8000',
+        help: 'Chroma server URL (local Docker or remote).',
+        showWhen: { key: 'mode', equals: ['server'] },
       },
       {
-        key: "authToken",
-        label: "Auth Token",
-        type: "password",
+        key: 'authToken',
+        label: 'Auth Token',
+        type: 'password',
         required: false,
         secret: true,
-        placeholder: "chroma-token",
-        help: "Optional static auth token for Chroma server.",
-        showWhen: { key: "mode", equals: ["server"] },
+        placeholder: 'chroma-token',
+        help: 'Optional static auth token for Chroma server.',
+        showWhen: { key: 'mode', equals: ['server'] },
       },
       {
-        key: "apiKey",
-        label: "API Key",
-        type: "password",
+        key: 'apiKey',
+        label: 'API Key',
+        type: 'password',
         required: true,
         secret: true,
-        placeholder: "sk_...",
-        help: "Chroma Cloud API Key.",
-        showWhen: { key: "mode", equals: ["cloud"] },
+        placeholder: 'sk_...',
+        help: 'Chroma Cloud API Key.',
+        showWhen: { key: 'mode', equals: ['cloud'] },
       },
       {
-        key: "tenant",
-        label: "Tenant",
-        type: "text",
+        key: 'tenant',
+        label: 'Tenant',
+        type: 'text',
         required: true,
-        defaultValue: "default_tenant",
-        help: "Tenant name for Chroma Cloud.",
-        showWhen: { key: "mode", equals: ["cloud"] },
+        defaultValue: 'default_tenant',
+        help: 'Tenant name for Chroma Cloud.',
+        showWhen: { key: 'mode', equals: ['cloud'] },
       },
       {
-        key: "database",
-        label: "Database",
-        type: "text",
+        key: 'database',
+        label: 'Database',
+        type: 'text',
         required: true,
-        defaultValue: "default_database",
-        help: "Database name for Chroma Cloud.",
-        showWhen: { key: "mode", equals: ["cloud"] },
+        defaultValue: 'default_database',
+        help: 'Database name for Chroma Cloud.',
+        showWhen: { key: 'mode', equals: ['cloud'] },
       },
       {
-        key: "collectionName",
-        label: "Collection name",
-        type: "text",
+        key: 'collectionName',
+        label: 'Collection name',
+        type: 'text',
         required: true,
-        defaultValue: "documents",
-        help: "Chroma collection to store and retrieve embeddings.",
+        defaultValue: 'documents',
+        help: 'Chroma collection to store and retrieve embeddings.',
       },
     ],
   },
 
   pgvector: {
-    id: "pgvector",
-    label: "pgvector",
+    id: 'pgvector',
+    label: 'pgvector',
     description:
-      "PostgreSQL extension for vector similarity search. Self-host vectors alongside your relational data.",
-    runtime: "both",
-    installStatus: "coming-soon",
-    docsUrl: "https://github.com/pgvector/pgvector",
+      'PostgreSQL extension for vector similarity search. Self-host vectors alongside your relational data.',
+    runtime: 'both',
+    installStatus: 'coming-soon',
+    docsUrl: 'https://github.com/pgvector/pgvector',
     serverDependencies: {
-      pg: "^8.11.0",
-      pgvector: "^0.2.0",
+      pg: '^8.11.0',
+      pgvector: '^0.2.0',
     },
     fields: [
       {
-        key: "connectionString",
-        label: "Connection string",
-        type: "password",
+        key: 'connectionString',
+        label: 'Connection string',
+        type: 'password',
         required: true,
         secret: true,
-        placeholder: "postgresql://user:pass@localhost:5432/db",
-        help: "Full PostgreSQL connection string.",
+        placeholder: 'postgresql://user:pass@localhost:5432/db',
+        help: 'Full PostgreSQL connection string.',
       },
       {
-        key: "tableName",
-        label: "Table name",
-        type: "text",
+        key: 'tableName',
+        label: 'Table name',
+        type: 'text',
         required: true,
-        defaultValue: "embeddings",
-        help: "The table used to store vector embeddings. Created automatically if absent.",
+        defaultValue: 'embeddings',
+        help: 'The table used to store vector embeddings. Created automatically if absent.',
       },
     ],
   },
 
   supabase: {
-    id: "supabase",
-    label: "Supabase",
+    id: 'supabase',
+    label: 'Supabase',
     description:
       "Postgres-backed vector store via the pgvector extension with Supabase's managed infrastructure.",
-    runtime: "cloud",
-    installStatus: "coming-soon",
-    docsUrl: "https://supabase.com/docs/guides/ai",
+    runtime: 'cloud',
+    installStatus: 'coming-soon',
+    docsUrl: 'https://supabase.com/docs/guides/ai',
     serverDependencies: {
-      "@supabase/supabase-js": "^2.43.0",
+      '@supabase/supabase-js': '^2.43.0',
     },
     fields: [
       {
-        key: "url",
-        label: "Project URL",
-        type: "text",
+        key: 'url',
+        label: 'Project URL',
+        type: 'text',
         required: true,
-        placeholder: "https://xyz.supabase.co",
-        help: "Your Supabase project URL.",
+        placeholder: 'https://xyz.supabase.co',
+        help: 'Your Supabase project URL.',
       },
       {
-        key: "serviceKey",
-        label: "Service role key",
-        type: "password",
+        key: 'serviceKey',
+        label: 'Service role key',
+        type: 'password',
         required: true,
         secret: true,
-        placeholder: "eyJhbGci...",
-        help: "Supabase service_role key (not the anon key). Stored as an env var.",
+        placeholder: 'eyJhbGci...',
+        help: 'Supabase service_role key (not the anon key). Stored as an env var.',
       },
       {
-        key: "tableName",
-        label: "Table name",
-        type: "text",
+        key: 'tableName',
+        label: 'Table name',
+        type: 'text',
         required: true,
-        defaultValue: "documents",
-        help: "Supabase table with a vector column for embeddings.",
+        defaultValue: 'documents',
+        help: 'Supabase table with a vector column for embeddings.',
       },
     ],
   },
-}
+};
 
-export const VECTOR_STORE_LIST: VectorStoreDescriptor[] =
-  Object.values(VECTOR_STORES)
+export const VECTOR_STORE_LIST: VectorStoreDescriptor[] = Object.values(VECTOR_STORES);
 
 export function getVectorStore(id: VectorStoreId): VectorStoreDescriptor {
-  return VECTOR_STORES[id]
+  return VECTOR_STORES[id];
 }
 
 /**
@@ -380,19 +426,19 @@ export function visibleFields(
   store: VectorStoreDescriptor,
   values: Record<string, string>,
   indexType?: IndexType,
-): import("@larkup/core/types").StoreField[] {
+): import('@larkup/core/types').StoreField[] {
   return store.fields.filter((field) => {
     // Sibling-field dependency (e.g. LanceDB mode → local/cloud fields)
     if (field.showWhen) {
-      const current = values[field.showWhen.key] ?? ""
-      if (!field.showWhen.equals.includes(current)) return false
+      const current = values[field.showWhen.key] ?? '';
+      if (!field.showWhen.equals.includes(current)) return false;
     }
     // Cross-concern dependency (e.g. indexType → sparse model)
     if (field.showWhenIndexType && indexType) {
-      if (!field.showWhenIndexType.includes(indexType)) return false
+      if (!field.showWhenIndexType.includes(indexType)) return false;
     }
-    return true
-  })
+    return true;
+  });
 }
 
 /**
@@ -404,11 +450,11 @@ export function validateStoreConfig(
   values: Record<string, string>,
   indexType?: IndexType,
 ): Record<string, string> {
-  const errors: Record<string, string> = {}
+  const errors: Record<string, string> = {};
   for (const field of visibleFields(store, values, indexType)) {
     if (field.required && !values[field.key]?.trim()) {
-      errors[field.key] = `${field.label} is required`
+      errors[field.key] = `${field.label} is required`;
     }
   }
-  return errors
+  return errors;
 }