endee-llamaindex 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# endee-llamaindex
+
+A LlamaIndex vector store integration for [Endee](https://endee.io) — enabling seamless RAG (Retrieval-Augmented Generation) workflows with the Endee vector database.
+
+## Installation
+
+```bash
+npm install endee-llamaindex
+# or
+pnpm add endee-llamaindex
+# or
+yarn add endee-llamaindex
+```
+
+## Prerequisites
+
+- An Endee account and API token
+- An existing index created in Endee
+- Node.js 18+
+
+## Quick Start
+
+```typescript
+import { EndeeVectorStore } from "endee-llamaindex";
+import { Document, Settings, storageContextFromDefaults, VectorStoreIndex } from "llamaindex";
+import { OpenAI, OpenAIEmbedding } from "@llamaindex/openai";
+
+// Configure your embedding model
+Settings.embedModel = new OpenAIEmbedding({
+  model: "text-embedding-3-small",
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+// Configure your LLM
+Settings.llm = new OpenAI({
+  model: "gpt-4o",
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+// Initialize the Endee vector store
+const vectorStore = new EndeeVectorStore({
+  indexName: "my-index",
+  apiToken: process.env.ENDEE_API_TOKEN,
+  chunkSize: 100,
+});
+
+// Create documents
+const document = new Document({
+  text: "Your document content here...",
+  id_: "doc-1",
+});
+
+// Index documents with storage context
+const storageContext = await storageContextFromDefaults({
+  vectorStore: vectorStore,
+});
+
+const index = await VectorStoreIndex.fromDocuments([document], { storageContext });
+
+// Query the index
+const queryEngine = index.asQueryEngine();
+const response = await queryEngine.query({
+  query: "What is the main topic?",
+});
+
+console.log(response.toString());
+```
+
+## Configuration
+
+### EndeeVectorStore Parameters
+
+| Parameter   | Type     | Description                                         |
+| ----------- | -------- | --------------------------------------------------- |
+| `indexName` | `string` | Name of your Endee index                            |
+| `apiToken`  | `string` | Your Endee API token                                |
+| `chunkSize` | `number` | Batch size for upserting vectors (recommended: 100) |
+
+## Usage Examples
+
+### Indexing Documents
+
+```typescript
+import fs from "node:fs/promises";
+
+const vectorStore = new EndeeVectorStore({
+  indexName: "knowledge-base",
+  apiToken: process.env.ENDEE_API_TOKEN,
+  chunkSize: 100,
+});
+
+const content = await fs.readFile("./documents/article.txt", "utf-8");
+const document = new Document({ text: content, id_: "article-1" });
+
+const storageContext = await storageContextFromDefaults({ vectorStore });
+const index = await VectorStoreIndex.fromDocuments([document], { storageContext });
+```
+
+### Querying an Existing Index
+
+```typescript
+const vectorStore = new EndeeVectorStore({
+  indexName: "knowledge-base",
+  apiToken: process.env.ENDEE_API_TOKEN,
+  chunkSize: 100,
+});
+
+// Load from existing vector store
+const index = await VectorStoreIndex.fromVectorStore(vectorStore);
+
+const queryEngine = index.asQueryEngine();
+const response = await queryEngine.query({
+  query: "Summarize the key points",
+});
+```
+
+### Deleting Documents
+
+```typescript
+const vectorStore = new EndeeVectorStore({
+  indexName: "knowledge-base",
+  apiToken: process.env.ENDEE_API_TOKEN,
+  chunkSize: 100,
+});
+
+// Delete by reference document ID
+await vectorStore.delete("doc-id-to-remove");
+```
+
+## API Reference
+
+### `EndeeVectorStore`
+
+#### Methods
+
+| Method                | Description                              |
+| --------------------- | ---------------------------------------- |
+| `add(nodes)`          | Add embedding nodes to the vector store  |
+| `query(query)`        | Query the vector store for similar nodes |
+| `delete(refDocId)`    | Delete vectors by reference document ID  |
+| `client()`            | Get the underlying Endee client          |
+| `index()`             | Get the Endee index instance             |
+
+## Dependencies
+
+- [llamaindex](https://www.npmjs.com/package/llamaindex) - LlamaIndex TypeScript SDK
+- [endee](https://www.npmjs.com/package/endee) - Endee vector database client
+
+## License
+
+ISC
+

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "endee-llamaindex",
+  "version": "1.0.0",
+  "description": "LlamaIndex integration with endee vector database",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Pankaj Singh (Endee Labs)",
+  "license": "ISC",
+  "dependencies": {
+    "@llamaindex/openai": "^0.4.22",
+    "endee": "^1.0.0",
+    "llamaindex": "^0.12.1"
+  }
+}

package/src/endeeClient.ts

@@ -0,0 +1,148 @@
+import { Endee } from "endee";
+import {
+  BaseNode,
+  BaseVectorStore,
+  Metadata,
+  metadataDictToNode,
+  nodeToMetadata,
+  VectorStoreBaseParams,
+  VectorStoreQuery,
+  VectorStoreQueryResult,
+} from "llamaindex";
+
+type EndeeParams = {
+  indexName: string;
+  apiToken: string;
+  chunkSize: number;
+} & VectorStoreBaseParams;
+
+export class EndeeVectorStore extends BaseVectorStore {
+  storesText: boolean = true;
+  private apiToken: string;
+  private indexName: string;
+  private chunkSize: number;
+  private db: any;
+
+  constructor(params: EndeeParams) {
+    super(params);
+    this.apiToken = params.apiToken;
+    this.indexName = params.indexName;
+    this.chunkSize = params.chunkSize;
+    this.db = new Endee(params.apiToken);
+  }
+
+  private getDB() {
+    if (!this.db) {
+      this.db = new Endee(this.apiToken);
+    }
+    return this.db;
+  }
+
+  client() {
+    return this.getDB();
+  }
+
+  async index() {
+    const db = this.getDB();
+    const index = await db.getIndex(this.indexName);
+    return index;
+  }
+
+  async add(embeddingResults: BaseNode<Metadata>[]): Promise<string[]> {
+    if (embeddingResults.length == 0) {
+      return [];
+    }
+
+    const idx: any = await this.index();
+    const nodes = embeddingResults.map((node) => {
+      const nodeRecord = this.nodeToRecord(node);
+
+      if (nodeRecord.meta.ref_doc_id) {
+        // adding refDoc id as prefix to the chunk to find them using refDoc id
+        nodeRecord.id = `${nodeRecord.meta.ref_doc_id}_chunk_${nodeRecord.id}`;
+      }
+      return nodeRecord;
+    });
+
+    for (let i = 0; i < nodes.length; i += this.chunkSize) {
+      const chunk = nodes.slice(i, i + this.chunkSize);
+      const result = await this.saveChunk(idx, chunk);
+      if (!result) {
+        throw new Error("Failed to save chunk");
+      }
+    }
+    return [];
+  }
+
+  protected async saveChunk(idx: any, chunk: any) {
+    try {
+      await idx.upsert(chunk);
+      return true;
+    } catch (err) {
+      const msg = `${err}`;
+      console.log(msg, err);
+      return false;
+    }
+  }
+
+  nodeToRecord(node: BaseNode<Metadata>) {
+    const id = node.id_.length ? node.id_ : null;
+    return {
+      id: id!,
+      vector: node.getEmbedding(),
+      meta: nodeToMetadata(node),
+    };
+  }
+
+  async query(
+    query: VectorStoreQuery,
+    _options?: object
+  ): Promise<VectorStoreQueryResult> {
+    const filter = "";
+    const defaultOptions: any = {
+      vector: query.queryEmbedding!,
+      topK: query.similarityTopK,
+      includeVectors: true,
+    };
+
+    if (filter) {
+      defaultOptions.filter = filter;
+    }
+
+    const idx = await this.index();
+    const results = await idx.query(defaultOptions);
+
+    const idList = results.map((row: any) => row.id);
+    if (idList.length == 0) {
+      return { nodes: [], similarities: [], ids: [] };
+    }
+
+    const nodes = results.map((row: any) => {
+      const node = metadataDictToNode(row.meta ?? {}, {
+        fallback: {
+          id: row.id,
+          text: row._node_content,
+          metadata: row.meta,
+          embedding: row.vector,
+        },
+      });
+      return node;
+    });
+
+    return {
+      nodes: nodes,
+      similarities: results.map((row: any) => row.similarity || 999),
+      ids: results.map((row: any) => row.id),
+    };
+  }
+
+  async delete(refDocId: string, deleteKwargs?: object): Promise<void> {
+    const [idx, index] = await Promise.all([
+      this.index(),
+      //to get the information about the index
+      this.db?.describeIndex(this.indexName),
+    ]);
+
+    await idx.deleteVector(refDocId);
+  }
+}