CAP AI plugin for Node.js
@cap-js/ai adds UI recommendations powered by SAP AI Core, simplified access to SAP AI Core resources, and vector embedding support for CAP applications.
Recommendations
The plugin adds SAP-RPT-1 recommendations to draft-enabled entities. Fields with a value help are included automatically:
@odata.draft.enabled
entity Books {
key ID : Integer;
title : String;
genre : Association to Genres;
price : Decimal;
}
annotate Genres with @cds.odata.valuelist;
Use @UI.RecommendationState to opt individual fields in or out:
annotate Books with {
genre @UI.RecommendationState: 0;
price @UI.RecommendationState;
}
A production deployment requires an SAP AI Core service binding. Without one, local development uses a mock implementation for UI smoke tests. See Recommendations for regression targets, request behavior, data handling, and deployment lifecycle.
SAP AI Core
The plugin provides an AICore CAP service for managing resource groups, deployments, and configurations:
const aiCore = await cds.connect.to('AICore');
const { resourceGroups, deployments } = aiCore.entities;
const groups = await aiCore.run(SELECT.from(resourceGroups));
await aiCore.stop(deployments, { id: '<deployment id>' });
See SAP AI Core integration for setup, supported queries, helper methods, and multitenancy.
Local vector embeddings with SQLite (experimental)
Warning
The SQLite extensions, local vector embeddings, local model management, and the related tooling are experimental facilities for local development. Breaking changes are expected, including changes caused by SQLite's synchronous function interface and by local model management. Use SAP HANA's vector engine for production vector workloads.
@cap-js/ai redirects the standard sqlite database so that VECTOR_EMBEDDING and the vector functions run locally against a real ONNX model — no external service, and no code changes versus SAP HANA. This lets you develop and test semantic search on SQLite. The following searches Bookshop's books by the meaning of their descriptions.
-
Install the local-development dependencies:
npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub \
@huggingface/tokenizers onnxruntime-node
This requires @sap/cds ^10.1 and @cap-js/sqlite ^3.1 (the package's other capabilities still support @sap/cds 9). No configuration is needed: the standard sqlite and sqlite:memory databases pick up the local implementation automatically.
-
Expose the search as an OData function. It ranks books by the cosine similarity between an embedded search phrase and each book's embedded description:
using { sap.capire.bookshop.Books } from '@capire/bookshop';
service SearchService {
function searchBooks(phrase : String) returns array of {
title : String;
relevance : Double;
};
}
const cds = require('@sap/cds')
module.exports = class SearchService extends cds.ApplicationService { init() {
this.on('searchBooks', ({ data: { phrase } }) =>
SELECT.from('sap.capire.bookshop.Books')
.columns`title, cosine_similarity(
vector_embedding(descr, 'DOCUMENT', 'SAP_GXY.20250407'),
vector_embedding(${phrase}, 'QUERY', 'SAP_GXY.20250407')) as relevance`
.orderBy`relevance desc`
)
return super.init()
}}
The model name is ignored on SQLite — the locally configured model is used — and honored on SAP HANA, so the same query runs unchanged on both. This embeds every book's description on each request; for repeated searches, persist the embeddings instead (see Local vector embeddings).
-
Run the app and call the function:
cds watch
In another terminal:
curl "http://localhost:4004/odata/v4/search/searchBooks(phrase='a%20haunting%20poem%20about%20lost%20love')"
@cap-js/ai looks for the configured model in the project's .cds/models first, then in ~/.cds/models. If it is missing, startup warns, downloads it to ~/.cds/models, and initializes it; later starts and other projects reuse that cache. The function returns the books ranked by relevance to the phrase.
The current default is sentence-transformers/all-MiniLM-L6-v2, chosen only as the most-downloaded reasonably small model matching the sentence-similarity task, ONNX format, and Apache-2.0 license. This is not a recommendation and may change while the feature is experimental — set cds.requires.db.embedding.model to pin it. Browse alternatives among trending Apache-2.0 sentence-similarity models with ONNX artifacts, then validate your choice with the provided tooling.
See Choosing a model and Local vector embeddings for compatibility checks, explicit or shared provisioning, runtime behavior, and limitations.
Advanced
- Recommendations — generated service shape, prediction context, regression targets, and lifecycle
- SAP AI Core integration — bindings, multitenancy, supported operations, and helper methods
- Local vector embeddings — SQLite kinds, model provisioning, SQL function behavior, and trust boundaries
- Choosing a model — Hugging Face filters, compatibility requirements, and size tradeoffs
- Local knowledge graph — experimental
SPARQL_EXECUTE and sparql_table support
Test the plugin locally
The sample application is in tests/bookshop.
npm test
Integration tests require an SAP AI Core binding:
cds bind ai-core -2 <your-ai-core-service-instance>
npm run test:hybrid
Support, feedback, and contributing
This project welcomes feature requests, bug reports, and contributions through GitHub issues. See the Contribution Guidelines for development information.
Security
Report potential security issues through the project's security policy, not through public issues.
Code of Conduct
Participation in this project is governed by the Code of Conduct.
Licensing
Copyright 2026 SAP SE or an SAP affiliate company and ai contributors. See LICENSE and the REUSE report.
