@mi8y/cap-agents-cds-vectorstore

@mi8y/cap-agents-cds-vectorstore

A simple LangChain vector store for SAP CAP applications.

This package gives you a VectorStore implementation backed by CAP CDS entities, so you can store embeddings and documents in your CAP application's database and use standard LangChain retrieval APIs for RAG and semantic search.

Installation

npm install @mi8y/cap-agents-cds-vectorstore

Then register the CDS model in your CAP project:

cds add agent-cds-vectorstore

This creates db/agent-cds-vectorstore.cds with two concrete entities (Documents and DocumentMetadata) under the default plugin.langchain.vectorstore namespace. The entities implement the package's reusable aspects with a default Vector(1536) embedding size (matching OpenAI text-embedding-3-small).

Requires:

• @sap/cds >= 10
• @langchain/core >= 1

What it adds

The plugin provides two reusable CDS aspects under the plugin.langchain.vectorstore namespace:

• VectorDocument — defines the shape for stored content and embeddings
• VectorDocumentMetadata — defines the shape for document metadata entries

Running cds add agent-cds-vectorstore generates default concrete entities implementing these aspects.

At runtime, CDSVectorStore reads and writes through CAP CDS, so it fits naturally into CAP applications and their existing database setup.

Usage

import { OpenAIEmbeddings } from "@langchain/openai";
import { CDSVectorStore } from "@mi8y/cap-agents-cds-vectorstore";

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vectorStore = new CDSVectorStore(embeddings, {
  name: "knowledge-base",
});

await vectorStore.addDocuments([
  {
    id: "doc-1",
    pageContent: "SAP CAP is a framework for building enterprise applications.",
    metadata: { source: "docs", topic: "cap" },
  },
  {
    id: "doc-2",
    pageContent:
      "LangChain helps build LLM apps with retrieval, tools, and agents.",
    metadata: { source: "docs", topic: "langchain" },
  },
]);

const results = await vectorStore.similaritySearch("What is SAP CAP?", 2);
console.log(results);

Customizing entities

1. Customizing embedding size

The default entities generated by cds add use Vector(1536). To use a different embedding size, just override the embedding field in your own concrete entity implementing the VectorDocument aspect.

...

entity Documents : managed, VectorDocument {
    embedding : Vector(3072); // ---> for 'text-embedding-3-large' model
    metadata  : Composition of many DocumentMetadata
                    on metadata.document = $self;
}

...

2. Customizing namespace and entity definitions

To use a different namespace or entity definitions (i.e. one definition per vector store), define your own entities implementing the package's aspects:

using { managed } from '@sap/cds/common';
using { VectorDocument, VectorDocumentMetadata } from '@mi8y/cap-agents-cds-vectorstore';

namespace my.app.vectorstore;

/**
 Vector store 1: Knowledge Base
 */

entity KnowledgeBaseDocuments : managed, VectorDocument {
    embedding   : Vector(3072);
    metadata    : Composition of many DocumentMetadata
                      on metadata.document = $self;
}

entity KnowledgeBaseDocumentMetadata : VectorDocumentMetadata {
    key document : Association to KnowledgeBaseDocuments;
}

/**
 Vector store 2: Customer Support
 */
entity CustomerSupportDocuments : managed, VectorDocument {
    embedding   : Vector(1536);
    metadata    : Composition of many DocumentMetadata
                      on metadata.document = $self;
}

entity CustomerSupportDocumentMetadata : VectorDocumentMetadata {
    key document : Association to CustomerSupportDocuments;
}

Then pass the custom entity names to CDSVectorStore:

const knowledgebaseVectorStore = new CDSVectorStore(embeddings, {
  name: "knowledge-base",
  fqnDocumentsEntity: "my.app.vectorstore.KnowledgeBaseDocuments",
  fqnDocumentMetadataEntity: "my.app.vectorstore.KnowledgeBaseDocumentMetadata",
});

const customersupportVectorStore = new CDSVectorStore(embeddings, {
  name: "customer-support",
  fqnDocumentsEntity: "my.app.vectorstore.CustomerSupportDocuments",
  fqnDocumentMetadataEntity:
    "my.app.vectorstore.CustomerSupportDocumentMetadata",
});

Field names (storeName, id, pageContent, embedding, metadata, name, value, document) are fixed across all implementations.

Use as a retriever

CDSVectorStore implements the standard LangChain vector store interface, so you can turn it into a retriever directly:

const retriever = vectorStore.asRetriever({
  k: 2,
});

const docs = await retriever.invoke("Explain CAP");

It also supports:

• similaritySearch
• similaritySearchWithScore
• maxMarginalRelevanceSearch

Metadata filtering

You can filter results by metadata when retrieving:

const retriever = vectorStore.asRetriever({
  k: 2,
  filter: {
    topic: "cap",
    priority: { $in: [2, 3] },
  },
});

const docs = await retriever.invoke("framework");

Supported operators:

• direct equality, like { topic: "cap" }
• $eq — equal to
• $ne — not equal to
• $in — match any of the provided values
• $notIn — exclude any of the provided values

API

new CDSVectorStore(embeddings, config)

Creates a CDS-backed vector store.

Config options:

• name: string Required store name. Use this to isolate one vector store from another in the same database.

• threshold?: number Optional similarity threshold. Defaults to 0.75.

• fqnDocumentsEntity?: string Fully-qualified CDS entity name for the documents table. Defaults to plugin.langchain.vectorstore.Documents.

• fqnDocumentMetadataEntity?: string Fully-qualified CDS entity name for the metadata table. Defaults to plugin.langchain.vectorstore.DocumentMetadata.

Static helpers

• CDSVectorStore.fromTexts(texts, metadatas, embeddings, config)
• CDSVectorStore.fromDocuments(docs, embeddings, config)
• CDSVectorStore.fromExistingIndex(embeddings, config)

Notes

• Document IDs are preserved if you provide them.
• If no ID is provided, the store generates one.
• The package uses cosine similarity for retrieval.
• The CDS model uses CAP's Vector type for embeddings.
• To extend the default embedding size, define your own concrete entities implementing the package's aspects.

License

MIT License