Add architecture files for cds-feature-ai-core, cds-feature-recommendations by lisajulia · Pull Request #111 · cap-java/cds-ai

lisajulia · 2026-07-06T11:40:31Z

add cds-feature-ai-core/architecture
add cds-feature-recommendations/architecture

hyperspace-insights · 2026-07-06T11:41:00Z

Summary

The following content is AI-generated and provides a summary of the pull request:

Add Architecture Documents and Improve READMEs

Documentation

📚 Added detailed architecture documentation for cds-feature-ai-core and cds-feature-recommendations, introduced a new cds-starter-ai README, and updated several existing READMEs with clarifications and additional context.

Changes

README.md: Updated project description to include SAP Document AI; clarified starter module scope; improved prerequisites section with per-plugin service binding info; updated fallback behavior wording; fixed integration-tests link; added a new GitHub Actions section documenting CI checks, static analysis tools, JaCoCo aggregation, and the release process.
cds-feature-ai-core/docs/architecture.md (new): Comprehensive architecture document covering purpose, dependencies (SAP AI SDK, Caffeine, Resilience4j, CAP MTX), CDS model, public API, key infrastructure classes, multi-tenancy, key flows (tenant subscribe/unsubscribe, inference client resolution with Mermaid diagram), tests, and quality tools.
cds-feature-ai-core/README.md: Expanded the sample section with a more specific description of the AdminService.Books demo scenario.
cds-feature-recommendations/docs/architecture.md (new): Architecture document covering purpose, dependencies (cds-feature-ai-core, Node.js CDS plugin, ExtensibilityService), key infrastructure classes, recommendation pipeline (Mermaid flowchart), no-prediction-cache invalidation flow, tests, and quality tools.
cds-feature-recommendations/README.md: Renamed "How It Works" to "Features"; added opt-out annotation example (@UI.RecommendationState: 0).
cds-starter-ai/README.md (new): New README documenting the cds-starter-ai convenience bundle — what it includes, Maven/npm setup, prerequisites, and note on cds-feature-sap-document-ai exclusion pending MT support.
cds-feature-sap-document-ai/README.md: Added Multi-Tenancy section to the table of contents and body; added a new Known Limitations section summarizing MT, annotation-based triggering, and OData API gaps.
integration-tests/README.md: Updated JaCoCo threshold description to clarify that SonarQube (not JaCoCo check goals) enforces coverage; replaced the per-module threshold table accordingly; added cds-feature-sap-document-ai to the coverage data sources list.

🔄 Regenerate and Update Summary
✏️ Insert as PR Description (deletes this comment)
🗑️ Delete comment

PR Bot Information

Version: 1.26.14

Output Template: Default Template
Correlation ID: 7f159260-792f-11f1-90a0-17a3f9ca90e6
Event Trigger: pull_request.opened
File Content Strategy: Full file content
LLM: anthropic--claude-4.6-sonnet
Summary Prompt: Default Prompt

hyperspace-insights

Two issues found: a broken relative link in cds-feature-recommendations/docs/architecture.md that points to a non-existent path, and a double-article typo ("an the") in cds-starter-ai/README.md. Both are straightforward to fix with the suggested corrections.

PR Bot Information

Version: 1.26.14

LLM: anthropic--claude-4.6-sonnet
File Content Strategy: Full file content
Event Trigger: pull_request.opened
Correlation ID: 7f159260-792f-11f1-90a0-17a3f9ca90e6

…lready has one

lisajulia · 2026-07-07T13:14:49Z

In any case: I suggest to wait for @agoerler's review of this before merging 👨‍💻

Co-authored-by: Marvin L <marvin.lindner@sap.com> Signed-off-by: Lisa Julia Nebel <lisajuliafog@yahoo.de>

lisajulia · 2026-07-10T08:24:35Z

@Schmarvinius: Thanks!
I will merge once @agoerler has reviewed + approved :)

agoerler

Hi @lisajulia, this is very helpful :-). I wish I had this overview right from the start.

Please consider to add a link from the readme files to the architecture files.

Intermediate feedback. I only have started to look at the CoreAI-part ...

agoerler · 2026-07-10T14:16:50Z

+
+## Purpose
+
+Automatically injects AI-powered field recommendations from the SAP RPT-1 tabular prediction foundation model into Fiori Elements OData responses for draft-enabled entities. Zero application code required.


consider to link to RPT-1 docs

agoerler · 2026-07-10T14:21:47Z

+| [`cds-feature-ai-core`](../../cds-feature-ai-core/README.md) | Provides the `AICore` CDS service and `AICoreService` API used to resolve the resource group, deployment ID, and inference `ApiClient` for the RPT-1 model. Recommendations cannot function without an active AI Core connection. |
+| `@cap-js/ai` (Node.js CDS plugin) | At CDS build time, the plugin adds the `SAP_Recommendations` navigation property to draft-enabled entities that have value-list fields. Without this (or a manual CDS extension), predictions are computed but not serialized in OData responses. |
+| `com.sap.ai.sdk.foundationmodels:sap-rpt` (SAP AI SDK) | Provides the RPT-1 model client used to call the `/predict` endpoint. |
+| `com.github.ben-manes.caffeine:caffeine` | Thread-safe in-process caching for the per-tenant entity skip cache (10k max, no TTL). |


I think here for this document it's perfect to describe the current state.

As you have a dependency to cds-services-utils you could consider to rather use com.sap.cds.services.utils.TenantAwareCache, which would free the plugin from all concerns wrt. tenant-specific cache invalidation.

Please add a section with left-overs/todos/blis/...

agoerler · 2026-07-10T14:24:45Z

+
+No dedicated CDS model file — the plugin relies on the `AICore` service model provided by `cds-feature-ai-core`, and on the `SAP_Recommendations` navigation property injected by the `@cap-js/ai` Node.js plugin (or added manually by the application).
+
+The Node plugin will automatically detect fields annotated with a value list, see [`README`](../README.md#enabling-recommendations).


annotated with a value list

please quote the annotation name although you link to the read.me

agoerler · 2026-07-10T14:31:17Z

+### Public API / Handlers
+
+No Java API — the plugin is entirely annotation-driven. Extend or annotate your CDS model to control which fields receive recommendations, see [`README`](../README.md#enabling-recommendations).
+Currently, it is not possible to hook into the recommendation result from application code to observe the injected output, nor to override the inference call itself ([#110](https://github.com/cap-java/cds-ai/issues/110)).


Please move or add this to a BLIs/TODOs/... section

I think a CAPish/Calesi-ish approach would to introduce a RecomendationService. A default implementation would use RPT-1. A mock implementation could generate something random.

You could handle the RecomendationService on-event to provide your own implementation. Or in an after-handler fine-tune the result.

agoerler · 2026-07-10T14:34:34Z

+| `RptModelSpec` | Static factory for the `ModelDeploymentSpec` targeting `sap-rpt-1-small`; used as the cache key for deployment resolution |
+| `RptInferenceClient` | Calls RPT-1 `/predict` endpoint; handles the synthetic `SAP_RECOMMENDATIONS_ID` index column for composite/non-string keys |
+| `RecommendationResultParser` | Type-coerces RPT-1 string output back to CDS primitive types; resolves `@Common.Text` descriptions from the database |
+| `RecommendationModelChangedHandler` | `@On(EVENT_MODEL_CHANGED)` — invalidates per-tenant entity cache on MTX model upgrade |


I think, later we can use the TenantAwareCache instead.

agoerler · 2026-07-10T15:58:39Z

+#### Recommendation Pipeline (OData GET on draft entity)
+
+```mermaid
+flowchart TD


would be nice to have swim lanes for

app server

AICore/RPT-1

the database

(but I am afraid the flowchart diagram does not support swim lanes)

agoerler · 2026-07-10T16:04:21Z

+
+## Purpose
+
+Bridges CAP Java to SAP AI Core's management and inference REST APIs, providing resource group management, deployment lifecycle, and inference client resolution as a standard CAP `RemoteService`. At the time of writing, `com.sap.ai.sdk:ai-core` offered no CAP integration — only raw REST API clients — so this plugin fills that gap.


as a standard CAP RemoteService

"as a CAP service"

A remote service bridges to a RESTish remote service that somehow understands CRUD operations

agoerler · 2026-07-10T16:05:03Z

+
+| Dependency | Why |
+|---|---|
+| `com.sap.ai.sdk:ai-core` (SAP AI SDK) | Provides the generated `DeploymentApi`, `ConfigurationApi`, `ResourceGroupApi`, and `ApiClient` types used to call the AI Core REST API. The plugin wraps these behind CDS events so callers never deal with the SDK directly. |


Suggested change

| `com.sap.ai.sdk:ai-core` (SAP AI SDK) | Provides the generated `DeploymentApi`, `ConfigurationApi`, `ResourceGroupApi`, and `ApiClient` types used to call the AI Core REST API. The plugin wraps these behind CDS events so callers never deal with the SDK directly. |

| `com.sap.ai.sdk:ai-core` (SAP AI SDK) | Provides the generated `DeploymentApi`, `ConfigurationApi`, `ResourceGroupApi`, and `ApiClient` types used to call the AI Core REST API. The plugin wraps these behind CDS events so callers never deal with the AI SDK directly. |

agoerler · 2026-07-10T16:10:15Z

+  // Events:
+  event resourceGroup    // in: (optional: tenantId — falls back to UserInfo.getTenant() from request context)  → out: resourceGroupId
+  event deploymentId     // in: resourceGroupId + ModelDeploymentSpec → out: deploymentId
+  event inferenceClient  // in: resourceGroupId + deploymentId → out: ApiClient


I don't find these "events" in cds-feature-ai-core/src/main/resources/cds/com.sap.cds/ai/index.cds.

agoerler · 2026-07-10T16:14:10Z

+```
+
+#### Inference Client Resolution
+


Please add a textual description of which problem you are solving here, why and how.

lisajulia requested review from Schmarvinius and samyuktaprabhu July 6, 2026 11:40

lisajulia requested a review from a team as a code owner July 6, 2026 11:40

hyperspace-insights Bot reviewed Jul 6, 2026

View reviewed changes

Comment thread cds-feature-recommendations/docs/architecture.md Outdated

Comment thread cds-starter-ai/README.md Outdated

lisajulia changed the title ~~Add architecture files~~ Add architecture files for cds-feature-ai-core, cds-featur-recommendations, add readme for cds-starter-ai, minor changes to other readme files Jul 6, 2026

lisajulia force-pushed the add-architecture-files branch 2 times, most recently from 138c964 to a355097 Compare July 6, 2026 11:47

lisajulia changed the title ~~Add architecture files for cds-feature-ai-core, cds-featur-recommendations, add readme for cds-starter-ai, minor changes to other readme files~~ Add architecture files for cds-feature-ai-core, cds-featur-recommendations Jul 6, 2026

lisajulia removed the request for review from samyuktaprabhu July 6, 2026 11:48

lisajulia changed the base branch from chore/import-sap-document-ai to main July 6, 2026 11:50

lisajulia changed the title ~~Add architecture files for cds-feature-ai-core, cds-featur-recommendations~~ Add architecture files for cds-feature-ai-core, cds-feature-recommendations Jul 6, 2026

lisajulia requested a review from agoerler July 6, 2026 12:13

Schmarvinius requested changes Jul 7, 2026

View reviewed changes

Comment thread cds-feature-recommendations/docs/architecture.md Outdated

Add architecture files for ai-core and recommendations, document ai a…

415193e

…lready has one

lisajulia force-pushed the add-architecture-files branch from a355097 to 415193e Compare July 7, 2026 13:10

Schmarvinius requested changes Jul 8, 2026

View reviewed changes

lisajulia and others added 4 commits July 8, 2026 11:09

Update cds-feature-ai-core/docs/architecture.md

95b1fc2

Co-authored-by: Marvin L <marvin.lindner@sap.com> Signed-off-by: Lisa Julia Nebel <lisajuliafog@yahoo.de>

Merge branch 'main' into add-architecture-files

dadd80c

Incorporate Marvins comments

1947f56

Update links to CI checks

5b60823

lisajulia requested a review from Schmarvinius July 9, 2026 12:46

Schmarvinius approved these changes Jul 9, 2026

View reviewed changes

agoerler reviewed Jul 10, 2026

View reviewed changes


		## Purpose

		Automatically injects AI-powered field recommendations from the SAP RPT-1 tabular prediction foundation model into Fiori Elements OData responses for draft-enabled entities. Zero application code required.


		No dedicated CDS model file — the plugin relies on the `AICore` service model provided by `cds-feature-ai-core`, and on the `SAP_Recommendations` navigation property injected by the `@cap-js/ai` Node.js plugin (or added manually by the application).

		The Node plugin will automatically detect fields annotated with a value list, see [`README`](../README.md#enabling-recommendations).


		## Purpose

		Bridges CAP Java to SAP AI Core's management and inference REST APIs, providing resource group management, deployment lifecycle, and inference client resolution as a standard CAP `RemoteService`. At the time of writing, `com.sap.ai.sdk:ai-core` offered no CAP integration — only raw REST API clients — so this plugin fills that gap.

	\| `com.sap.ai.sdk:ai-core` (SAP AI SDK) \| Provides the generated `DeploymentApi`, `ConfigurationApi`, `ResourceGroupApi`, and `ApiClient` types used to call the AI Core REST API. The plugin wraps these behind CDS events so callers never deal with the SDK directly. \|
	\| `com.sap.ai.sdk:ai-core` (SAP AI SDK) \| Provides the generated `DeploymentApi`, `ConfigurationApi`, `ResourceGroupApi`, and `ApiClient` types used to call the AI Core REST API. The plugin wraps these behind CDS events so callers never deal with the AI SDK directly. \|

Uh oh!

Conversation

lisajulia commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hyperspace-insights Bot commented Jul 6, 2026

Summary

Add Architecture Documents and Improve READMEs

Documentation

Changes

Uh oh!

hyperspace-insights Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lisajulia commented Jul 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lisajulia commented Jul 10, 2026

Uh oh!

agoerler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lisajulia commented Jul 6, 2026 •

edited

Loading