@bridgerust/embex 0.1.13 → 0.1.15

package/README.md

@@ -1,139 +1,112 @@
 # Embex (Node.js)
 
-**The Universal Vector Database ORM.** One API for Qdrant, Pinecone, Chroma, LanceDB, and more.
+**The fastest way to add vector search to your app.**
 
-Embex is a high-performance, universal client for vector databases, built on a shared Rust core related to [BridgeRust](https://github.com/bridgerust/bridgerust).
+Embex is a universal vector database client that lets you start with zero setup and scale to production without rewriting code.
 
 ## 🚀 Features
 
-- **Unified API**: Switch providers instantly. "Write once, run anywhere."
-- **Performance**: Powered by Rust with SIMD acceleration.
+- **Start Simple**: Use LanceDB (embedded) for zero-setup local development.
+- **Unified API**: Switch to Qdrant, Pinecone, or Milvus just by changing the config.
+- **Performance**: Powered by a shared Rust core with SIMD acceleration.
 - **Type Safety**: Full TypeScript support.
 
 ## 📦 Installation
 
 ```bash
-npm install @bridgerust/embex
-```
-
-```bash
-yarn add @bridgerust/embex
-```
-
-```bash
-bun add @bridgerust/embex
+npm install @bridgerust/embex lancedb @xenova/transformers
 ```
 
 ## ⚡ Quick Start
 
-**Try Embex in 30 seconds - No setup required!** Uses LanceDB embedded mode (no server needed).
+Build semantic search in 5 minutes using **LanceDB** (embedded) and local embeddings. No API keys or Docker needed!
 
 ```typescript
-import { EmbexClient } from "@bridgerust/embex";
+import { EmbexClient, Vector } from "@bridgerust/embex";
+import { pipeline } from "@xenova/transformers";
 
 async function main() {
-  // LanceDB embedded - zero setup, just a local path
-  const client = await EmbexClient.newAsync("lancedb", "./data");
-  const collection = client.collection("documents");
-
-  // Create collection
-  await collection.create(768, "cosine");
-
-  // Insert data
-  await collection.insert([
-    {
-      id: "1",
-      vector: Array(768).fill(0.1),
-      metadata: { text: "Hello World" },
-    },
-  ]);
-
-  // Search
-  const results = await collection.search(Array(768).fill(0.1), 5);
-  console.log(results.results);
+  // 1. Setup Embedding Model
+  const generateEmbedding = await pipeline(
+    "feature-extraction",
+    "Xenova/all-MiniLM-L6-v2"
+  );
+  const embed = async (text: string) => {
+    const output = await generateEmbedding(text, {
+      pooling: "mean",
+      normalize: true,
+    });
+    return Array.from(output.data);
+  };
+
+  // 2. Initialize Client (uses LanceDB embedded)
+  const client = await EmbexClient.newAsync("lancedb://./data");
+
+  // 3. Create Collection (384 dimensions for MiniLM)
+  await client.createCollection("products", 384);
+
+  // 4. Insert Data
+  const documents = [
+    { id: "1", text: "Apple iPhone 15", category: "electronics" },
+    { id: "2", text: "Samsung Galaxy S24", category: "electronics" },
+  ];
+
+  const vectors: Vector[] = [];
+  for (const doc of documents) {
+    vectors.push({
+      id: doc.id,
+      vector: await embed(doc.text),
+      metadata: { text: doc.text },
+    });
+  }
+
+  await client.insert("products", vectors);
+
+  // 5. Search
+  const query = "smartphone";
+  const results = await client.search({
+    collection_name: "products",
+    vector: await embed(query),
+    limit: 1,
+  });
+
+  console.log(`Query: '${query}'`);
+  console.log(`Match: ${results[0].metadata.text}`);
 }
 
 main();
 ```
 
-**Run it:** `npx tsx examples/lancedb/node/quickstart.ts`
-
-### All Provider Quick Starts
+## 🗺️ Development → Production Roadmap
 
-Try Embex with any provider! Same API, different backend:
+| Stage               | Recommendation        | Why?                                |
+| :------------------ | :-------------------- | :---------------------------------- |
+| **Day 1: Learning** | **LanceDB**           | Embedded. Zero setup. Free.         |
+| **Week 2: Staging** | **Qdrant / Pinecone** | Managed cloud. Connection pooling.  |
+| **Month 1: Scale**  | **Milvus**            | Distributed. Billion-scale vectors. |
+| **Anytime**         | **PgVector**          | You already use PostgreSQL.         |
 
-| Provider     | Setup           | Quick Start                                    |
-| ------------ | --------------- | ---------------------------------------------- |
-| **LanceDB**  | None (embedded) | `npx tsx examples/lancedb/node/quickstart.ts`  |
-| **Qdrant**   | Docker server   | `npx tsx examples/qdrant/node/quickstart.ts`   |
-| **Pinecone** | API key         | `npx tsx examples/pinecone/node/quickstart.ts` |
-| **Chroma**   | Optional server | `npx tsx examples/chroma/node/quickstart.ts`   |
+## ☁️ Switch Provider (Zero Code Changes)
 
-> 💡 **Same API everywhere!** Just change the provider name - all code stays the same. See [examples/README.md](../../../../examples/README.md) for setup instructions.
+Ready for production? Just change the initialization line.
 
-### 5. Filtered Search (Builder Pattern)
+**From LanceDB (Dev):**
 
 ```typescript
-const results = await collection.buildSearch([0.1, 0.2, ...])
-  .limit(10)
-  .filter({
-    course: "CS101"
-  })
-  .execute();
+const client = await EmbexClient.newAsync("lancedb://./data");
 ```
 
-## ☁️ Connecting to Cloud Providers
-
-To connect to managed services like Pinecone, Qdrant Cloud, or Zilliz (Milvus), simply provide your API key and endpoint URL.
+**To Qdrant Cloud (Prod):**
 
 ```typescript
-import { EmbexClient } from "@bridgerust/embex";
-
-// Connect to Pinecone
 const client = new EmbexClient(
-  "pinecone",
-  "https://index-name.svc.pinecone.io",
-  process.env.PINECONE_API_KEY
-);
-
-// Connect to Qdrant Cloud
-const qdrantClient = new EmbexClient(
   "qdrant",
-  "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
+  "https://your-cluster.qdrant.io",
   process.env.QDRANT_API_KEY
 );
 ```
 
-### Official Documentation & API Keys
-
-Need help finding your API key? Check the official provider documentation:
-
-- **Pinecone**: [Authentication & API Keys](https://docs.pinecone.io/guides/get-started/quickstart#2-get-an-api-key)
-- **Qdrant**: [Cloud Authentication](https://qdrant.tech/documentation/cloud/authentication/)
-- **Milvus (Zilliz)**: [Manage Credentials](https://docs.zilliz.com/docs/manage-api-keys)
-- **Weaviate**: [Authentication](https://weaviate.io/developers/weaviate/configuration/authentication)
-- **Chroma**: [Auth & Client Settings](https://docs.trychroma.com/guides#authentication)
-
-## 🔌 Supported Providers
-
-| Provider | Key        | Async Init? |
-| -------- | ---------- | ----------- |
-| Qdrant   | `qdrant`   | No          |
-| Chroma   | `chroma`   | No          |
-| Pinecone | `pinecone` | No          |
-| Weaviate | `weaviate` | No          |
-| LanceDB  | `lancedb`  | **Yes**     |
-| Milvus   | `milvus`   | **Yes**     |
-| PgVector | `pgvector` | **Yes**     |
-
-## ⭐ Star Us
-
-If you find Embex useful, please star the repository! It helps others discover the project.
-
-[⭐ Star on GitHub](https://github.com/bridgerust/bridgerust)
-
 ## 🔗 Resources
 
-- **Main Repository**: [github.com/bridgerust/bridgerust](https://github.com/bridgerust/bridgerust)
-- **Issues**: [github.com/bridgerust/bridgerust/issues](https://github.com/bridgerust/bridgerust/issues)
-- **Documentation**: [Full Docs](https://github.com/bridgerust/bridgerust/tree/main/bindings/node/%40bridgerust/embex)
+- **Full Documentation**: [bridgerust.dev/embex](https://bridgerust.dev/embex/introduction)
+- **GitHub**: [bridgerust/bridgerust](https://github.com/bridgerust/bridgerust)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./src";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src"), exports);

package/dist/native.d.ts

@@ -0,0 +1,138 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class Collection {
+  /** Insert points into the collection. */
+  insert(points: Array<Point>): Promise<void>
+  /** Search for similar vectors. */
+  query(vector: Array<number>, options?: SearchOptions | undefined | null): Promise<SearchResponse>
+  /**
+   * Search for similar vectors with direct parameters.
+   *
+   * @param vector - Query vector
+   * @param topK - Number of results to return (default: 10)
+   * @param filter - Optional metadata filter
+   * @param includeMetadata - Whether to include metadata (default: true)
+   * @param includeVector - Whether to include vectors (default: false)
+   */
+  search(vector: Array<number>, topK?: number | undefined | null, filter?: any | undefined | null, includeMetadata?: boolean | undefined | null, includeVector?: boolean | undefined | null): Promise<SearchResponse>
+  /** Search using a builder pattern. */
+  buildSearch(vector: Array<number>): SearchBuilder
+  /** Query using a builder pattern (filter-only, no vector search). */
+  buildQuery(): QueryBuilder
+  /** Update metadata for points in the collection. */
+  updateMetadata(updates: Array<MetadataUpdate>): Promise<void>
+  delete(ids: Array<string>): Promise<void>
+  deleteCollection(): Promise<void>
+  create(dimension: number, distance: string): Promise<void>
+  /**
+   * Create the collection with optional dimension.
+   *
+   * For providers like Chroma that infer dimension from the first insert,
+   * you can pass `undefined` for dimension. For other providers, dimension is required.
+   *
+   * @param dimension - Optional dimension. Use `undefined` for Chroma (infers from first insert).
+   * @param distance - Distance metric ("cosine", "euclidean", or "dot").
+   */
+  createAuto(dimension?: number | undefined | null, distance?: string | undefined | null): Promise<void>
+  insertBatch(points: Array<Point>, batchSize?: number | undefined | null, parallel?: number | undefined | null): Promise<void>
+}
+
+/** Main client for the Embex vector database. */
+export declare class EmbexClient {
+  /**
+   * Create a new Embex client.
+   *
+   * @param provider - The database provider (e.g., 'qdrant', 'pinecone').
+   * @param url - The connection URL.
+   * @param apiKey - Optional API key.
+   */
+  constructor(provider: string, url: string, apiKey?: string | undefined | null)
+  /**
+   * Create a new Embex client with async initialization.
+   * Required for providers like 'milvus', 'pgvector', and 'lancedb'.
+   *
+   * @param provider - The database provider.
+   * @param url - The connection URL.
+   * @param apiKey - Optional API key.
+   */
+  static newAsync(provider: string, url: string, apiKey?: string | undefined | null): Promise<EmbexClient>
+  collection(name: string): Collection
+  /**
+   * Run database migrations.
+   *
+   * @param migrations - Array of migration objects
+   * {
+   *   version: string,
+   *   operations: [{ type: 'create_collection', schema: ... }, { type: 'delete_collection', name: ... }],
+   *   down_operations: [...]
+   * }
+   */
+  runMigrations(migrations: Array<MigrationInput>): Promise<void>
+}
+
+export declare class QueryBuilder {
+  limit(limit: number): QueryBuilder
+  offset(offset: number): QueryBuilder
+  includeVector(include: boolean): QueryBuilder
+  includeMetadata(include: boolean): QueryBuilder
+  filter(filter: any): QueryBuilder
+  aggregation(aggType: string): QueryBuilder
+  execute(): Promise<SearchResponse>
+}
+
+export declare class SearchBuilder {
+  limit(limit: number): SearchBuilder
+  offset(offset: number): SearchBuilder
+  includeVector(include: boolean): SearchBuilder
+  includeMetadata(include: boolean): SearchBuilder
+  filter(filter: any): SearchBuilder
+  aggregation(aggType: string): SearchBuilder
+  execute(): Promise<SearchResponse>
+}
+
+export declare function cli(args: Array<string>): Promise<void>
+
+export interface MetadataUpdate {
+  /** Point ID to update. */
+  id: string
+  /** Metadata updates to apply. */
+  updates: Record<string, any>
+}
+
+export interface MigrationInput {
+  version: string
+  operations?: any
+  downOperations?: any
+}
+
+/** A point in the vector database. */
+export interface Point {
+  id: string
+  vector: Array<number>
+  metadata?: Record<string, any>
+}
+
+export interface SearchOptions {
+  /** Number of results to return. */
+  limit?: number
+  /** Metadata filter. */
+  filter?: any
+  /** Whether to include metadata in results. */
+  includeMetadata?: boolean
+  /** Whether to include vector in results. */
+  includeVector?: boolean
+  /** Pagination offset. */
+  offset?: number
+}
+
+export interface SearchResponse {
+  results: Array<SearchResult>
+  aggregations: Record<string, any>
+}
+
+export interface SearchResult {
+  id: string
+  score: number
+  vector?: Array<number>
+  metadata?: Record<string, any>
+}