Review: Full prototype implementation

[Schmarvinius]

This PR contains the full prototype implementation for review purposes.

Note: This PR is for code review only — do not merge it. Close it once the review is complete.

[hyperspace-insights]

Summary

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

---

Feat: Initial Prototype for CAP Java AI Integration

New Feature

This pull request introduces the initial prototype for a comprehensive AI feature integration for CAP Java applications. It includes two main libraries, a full testing suite, CI/CD pipelines, and a sample application.

✨ cds-feature-ai-core: A foundational module that provides a seamless bridge to SAP AI Core.

• Exposes AI Core resources (Resource Groups, Deployments, Configurations) as a native CAP service (AICore).
• Supports full CRUD operations and custom actions via CQN and OData.
• Includes robust multi-tenancy support with automatic resource group management during tenant onboarding/offboarding.
• Features a resilient client with caching, retry logic, and exponential backoff for AI Core API calls.
• Provides a mock implementation for local development without needing an AI Core binding.

✨ cds-feature-recommendations: A powerful feature that delivers AI-powered field recommendations in Fiori UIs.

• Automatically hooks into draft-enabled entities.
• Uses historical data and the RPT-1 foundation model to predict values for fields with value lists.
• Integrates with Fiori Elements to display suggestions directly in the UI.

Note: This PR is for code review only and should be closed once the review is complete.

Changes

This is a large initial commit that scaffolds the entire project. The changes are summarized by module:

• Project Scaffolding (/, .github/):

  • pom.xml: Established a multi-module Maven project structure.
  • README.md, LICENSE, CONTRIBUTING.md: Added standard project documentation and legal files.
  • .github/workflows/: Set up a comprehensive CI/CD pipeline using GitHub Actions for PR validation, security scanning (CodeQL, SonarQube, BlackDuck), and release deployment.
  • .github/actions/: Created reusable composite actions for build, test, scan, and deployment steps.

• Core AI Integration (cds-feature-ai-core/):

  • Implemented the AICoreService to interact with the SAP AI SDK, manage deployments, and handle predictions.
  • Added AICoreServiceImpl with caching and retry logic, and MockAICoreServiceImpl for local testing.
  • Created AICoreSetupHandler to manage multi-tenancy lifecycle events.
  • Defined the AICore CDS service model in cds/com.sap.cds/ai/index.cds.

• Field Recommendations (cds-feature-recommendations/):

  • FioriRecommendationHandler.java: Implemented the main handler to intercept read events on draft entities, build context, and trigger predictions.
  • RptInferenceClient.java: A client to communicate with the RPT-1 model.
  • RecommendationContextBuilder.java & RecommendationResultParser.java: Helpers to prepare data for the AI model and parse its response for the UI.

• Starter & Aggregators (cds-starter-ai/, coverage-report/):

  • cds-starter-ai/: Created a starter module for easy dependency management.
  • coverage-report/: Added a module to aggregate JaCoCo code coverage reports.

• Testing (integration-tests/):

  • Developed a full suite of integration tests for a Spring Boot application.
  • spring/: Contains tests for core service functionality, OData delegation, and the recommendation feature.
  • mtx-local/: Contains tests for multi-tenancy scenarios, including tenant subscription and isolation.

• Sample Application (samples/bookshop/):

  • Included a complete CAP Java bookshop application to demonstrate the AI features.
  • The AdminService is draft-enabled to showcase field recommendations.
  • The AICoreShowcaseService provides examples of how to programmatically interact with the AICoreService.

---

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

PR Bot Information

Version: 1.21.0 | 📖 Documentation | 🚨 Create Incident | 💬 Feedback

• Output Template: Default Template
• File Content Strategy: Diffs only
• Summary Prompt: Default Prompt
• Event Trigger: pull_request.opened
• Correlation ID: ea28e160-ae3d-46b6-8a69-51c04ea3ba2b
• LLM: gemini-2.5-pro

---

💌 Have ideas or want to contribute? Create an issue and share your thoughts with us!
📑 Check out the documentation for more information.
📬 Subscribe to the Hyperspace PR Bot DL to get the latest announcements and pilot features!

Made with ❤️ by Hyperspace.

[hyperspace-insights]

This pull request is a large but well-structured initial implementation of a new feature, including comprehensive CI/CD pipelines and documentation. I've identified a few areas for improvement regarding maintainability and a minor bug in the cache-clearing logic. Overall, the quality is high.

PR Bot Information

Version: 1.21.0 | 📖 Documentation | 🚨 Create Incident | 💬 Feedback

• File Content Strategy: Diffs only
• Event Trigger: pull_request.opened
• Correlation ID: ea28e160-ae3d-46b6-8a69-51c04ea3ba2b
• LLM: gemini-2.5-pro

[agoerler]

Some feedback. (I have not looked at the ai core feature in detail so far).

Some general findings:

• I like the separation into two plugins very much :-)
• please move the APIs to dedicated api packages
• looks very tidy overall

AI Core

• the AICoreService interface could be possibly segragated into
  • the part to manage resource groups and deployment IDs
  • the inference API - maybe you don't need this part at all but could directly register ApiClient as a technical service or Spring bean.
• the tenant must not appear in the AICoreService API. The user of the AICoreService should be tenant-agnostic but the implementation should be tenant-aware
• you should provide a mock implementation of the APIClient that can use langchain4j to use local models
• ideally you externalize the mapping of symbolic inference model names to actual model names so that we can use differently expensive models for testing and in production

Recommendations

• make sure the annotations can also be added manually
• consider to register the RecommendationClient as a service so that the application could overwrite the RecommendationClient's on-handler to compute recommendations somehow differently (could be done later)
• design the RecommendationClient API so that it's not too tightly coupled to RPT-1

[agoerler]

let's add a cds add flavor

[agoerler]

Please consider to offer a slimmed-down version of @cap-js/ai that does not contain the model artifacts. Or exclude the model artifacts from cds-feature-recommendations.

[agoerler]

Suggested change

	| `AICore.resourceGroups` | READ, CREATE, DELETE | Resource group lifecycle, supports label filtering by `tenantId` |
	| `AICore.resourceGroups` | READ, CREATE, DELETE | Resource group lifecycle, supports label filtering |

make sure that the API is always restricted to the current tenant and does not expose other tenants' resource groups

[agoerler]

Suggested change

	// Get the resource group ID for a CDS tenant
	String rgId = aiCoreService.resourceGroupForTenant(tenantId);
	// Get the resource group ID for the current tenant
	String rgId = aiCoreService.resourceGroup();

[agoerler]

Ideally you do without this config but evaluate the properties under https://pages.github.tools.sap/cap/docs/java/developing-applications/properties#cds-multiTenancy

[agoerler]

The implementation can obtain the tenantId from the tenant provider service. As there seems to be exactly one resource group per tenant we could simplify this:

// Resolve a deployment and obtain a configured ApiClient for it
String resourceGroupId = aiCore.resourceGroup();
String deploymentId = aiCore.deploymentId(resourceGroupId, RptModelSpec.rpt1());
ApiClient client = aiCore.inferenceClient(resourceGroupId, deploymentId);

the only variable appears to the model for which there appears to be exactly one deployment -> we can further simplify the API to

AICoreService aiCore = runtime.getServiceCatalog()
    .getService(AICoreService.class, AICoreService.DEFAULT_NAME);

ApiClient client = aiCore.inferenceClient(RptModelSpec.rpt1());

We could also use dependency injection:

@Autowired
AICoreService aiCore;

ApiClient client = aiCore.inferenceClient(RptModelSpec.rpt1());

and if we add an option to configure service instances for the ApiClient in the application.yaml (sketchy!):

cds.api.core.client:
  -name : myRpt1Client
    model: RPT1

then we could use qualified dependency injection

@Autowired
@Qualifier("myRpt1Client")
ApiClient rpt1;

If we externalize the model config for the inference client we can have different models in production as well as on localhost/CI so that we don't have to burn expensive tokens for testing but can rather use something cheap for this purpose.

[agoerler]

a bit unexpected to find this here

[agoerler]

Some feedback. (I have not looked at the ai core feature in detail so far).

Some general findings:

• I like the separation into two plugins very much :-)
• please move the APIs to dedicated api packages
• looks very tidy overall

AI Core

• the AICoreService interface could be possibly segragated into
  • the part to manage resource groups and deployment IDs
  • the inference API - maybe you don't need this part at all but could directly register ApiClient as a technical service or Spring bean.
• the tenant must not appear in the AICoreService API. The user of the AICoreService should be tenant-agnostic but the implementation should be tenant-aware
• you should provide a mock implementation of the APIClient that can use langchain4j to use local models
• ideally you externalize the mapping of symbolic inference model names to actual model names so that we can use differently expensive models for testing and in production

Recommendations

• make sure the annotations can also be added manually
• consider to register the RecommendationClient as a service so that the application could overwrite the RecommendationClient's on-handler to compute recommendations somehow differently (could be done later)
• design the RecommendationClient API so that it's not too tightly coupled to RPT-1

[lisajulia]

Some feedback. (I have not looked at the ai core feature in detail so far).

Some general findings:

• I like the separation into two plugins very much :-)
• please move the APIs to dedicated api packages
• looks very tidy overall

AI Core

• the AICoreService interface could be possibly segragated into

  • the part to manage resource groups and deployment IDs
  • the inference API - maybe you don't need this part at all but could directly register ApiClient as a technical service or Spring bean.

• the tenant must not appear in the AICoreService API. The user of the AICoreService should be tenant-agnostic but the implementation should be tenant-aware

• you should provide a mock implementation of the APIClient that can use langchain4j to use local models

• ideally you externalize the mapping of symbolic inference model names to actual model names so that we can use differently expensive models for testing and in production

Recommendations

• make sure the annotations can also be added manually
• consider to register the RecommendationClient as a service so that the application could overwrite the RecommendationClient's on-handler to compute recommendations somehow differently (could be done later)
• design the RecommendationClient API so that it's not too tightly coupled to RPT-1

Thanks!

[BraunMatthias]

Suggested change

	String DEFAULT_NAME = "AICore";
	String DEFAULT_NAME = "AICoreService$Default";

*Service$Default is standard pattern for CAP provided services

[BraunMatthias]

handlers are registered to concrete services and the called service is always always propagated via EventContext. Hence there is no need to store the ServiceImpl as reference. Also the handler should be fully decoupled from the concrete service implementation.

[BraunMatthias]

the constant is comple-safe

[BraunMatthias]

the constant is comple-safe

[BraunMatthias]

better switch to typesafe handler APIs

example: https://github.wdf.sap.corp/cds-java/cds-services/blob/3031b1939120424607c4a28bd134efced72f0b21/cds-feature-auditlog-v2/src/main/java/com/sap/cds/feature/auditlog/v2/AuditLogV2Handler.java#L81

[BraunMatthias]

Shouldn't be the indicator rather be an annotation instead of a string prefix?

[Schmarvinius]

As discussed: AICoreApplicationServiceHandler will be deleted since it introduces too many edge cases
Consumers should write the projection use case themselves!

[BraunMatthias]

proposal:

"cds.AICore.client.maxRetries"
"cds.AICore.client.initialDelayMs"
"cds.AICore.resourceGroup.default"
"cds.AICore.resourceGroup.prefix"

[Schmarvinius]

I named them cds.ai.core.* in my branch
for recommendation, it then would be cds.ai.recommendations.*

[MattSchur]

For embeddings I could imagine cds.ai.embeddings with different profiles, e.g. using HANA NLP or AI Core models:

  cds.ai:
    embeddings:
        # Local HANA model - no remote source
        default:
          model: SAP_NEB.20240715

        large:
          model: text-embedding-3-large
          remoteSource: AICore
          options:
            execution_params:
              timeout: 60000

We could (later) add cds-feature-embeddings that uses feature-ai-core to provide a CDS4j EmbeddingService integration and does the HANA setup for using embedding models from AI Core.

[BraunMatthias]

Suggested change

	@After(event = DeploymentService.EVENT_SUBSCRIBE)
	@After

[BraunMatthias]

I'd expect all this implemented actions in handlers (same for mock variant)

[MattSchur]

Should we add a circuit breaker?

[MattSchur]

For embeddings I could imagine cds.ai.embeddings with different profiles, e.g. using HANA NLP or AI Core models:

  cds.ai:
    embeddings:
        # Local HANA model - no remote source
        default:
          model: SAP_NEB.20240715

        large:
          model: text-embedding-3-large
          remoteSource: AICore
          options:
            execution_params:
              timeout: 60000

We could (later) add cds-feature-embeddings that uses feature-ai-core to provide a CDS4j EmbeddingService integration and does the HANA setup for using embedding models from AI Core.

[MattSchur]

Do we want to have an integration point for the ai-sdk-java and other higher-level APIs like LangChain4j? How would this look like?

[MattSchur]

ApiClient seems to be a low level technical API. On top of that we could (later) have integrations with the ai-sdk and other higher level APIs like LangChain4j.