From 898608c2e8dd1b0f3cc2849b63a63bfba6e04d04 Mon Sep 17 00:00:00 2001
From: kiwiflyer <17278194+kiwiflyer@users.noreply.github.com>
Date: Thu, 19 Nov 2026 14:15:31 +0000
Subject: [PATCH] ai-services: add the AI Services API plugin and UI section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Adds a native API plugin (plugins/api/ai-services) and a ui/ section
that let an operator source open-weight LLMs, deploy them on NVIDIA GPU
capacity, tune them through profiles, and sell them to tenants as
OpenAI-compatible endpoints.
The plugin is the front door only — auth, RBAC, async jobs, events,
usage and limits. It delegates over mTLS to an external reconciler,
which is the component that touches GPU resources, CKS and the serving
layer; that engine is not in this change.
* 58 API commands: 38 v1, registered always, and 20 v2, registered
only when the global setting ai.services.v2.enabled is on (default
false), so a GA install does not advertise an API for features it
is not running.
* A UI section of 19 screens. Each route carries a permission, so
CloudStack drops any screen whose command the caller cannot call,
and the Tier 2 screens appear and disappear with that one setting.
* Ten ai.services.* ConfigKeys, including the engine URLs and its
mTLS material.
* Default role access declared on @APICommand(authorized = ...), so
there is no migration, no commands.properties and no operator step.
An explicit role_permissions rule still wins.
The change is additive. Four existing files are touched: plugins/pom.xml
and client/pom.xml to build and bundle the module, ui/src/config/
router.js to register the section, and ui/public/locales/en.json, into
which 150 keys are appended without reordering or reformatting anything
already there.
Tested against a live 4.23.0.0 management server with the plugin loaded:
481 JUnit tests and checkstyle clean; listApis goes 865 -> 903 with the
plugin and -> 923 with v2 enabled, exactly the declared commands; Marvin
covers all 58 commands across three default roles, allowed and denied;
and the Playwright suite passes 40 with 7 skipped against the plugin and
the UI in the same management server.
Not yet exercised: a full reactor build, any live 24.0.0-SNAPSHOT
server, and real GPU capacity — the simulator's cards are simulated.
---
client/pom.xml | 5 +
plugins/api/ai-services/README.md | 139 ++
plugins/api/ai-services/pom.xml | 122 +
.../cloudstack/ai/AiServicesConfig.java | 134 ++
.../cloudstack/ai/AiServicesEvents.java | 88 +
.../cloudstack/ai/AiServicesManagerImpl.java | 527 ++++
.../cloudstack/ai/AiServicesSchema.java | 182 ++
.../cloudstack/ai/AiServicesService.java | 68 +
.../cloudstack/ai/AiServicesUsageTypes.java | 60 +
.../ai/api/command/AiServicesAsyncCmd.java | 154 ++
.../ai/api/command/AiServicesListCmd.java | 106 +
.../ai/api/command/AiServicesSyncCmd.java | 147 ++
.../ai/api/command/ApproveAiModelCmd.java | 70 +
.../api/command/AssignAiTuningProfileCmd.java | 89 +
.../ai/api/command/CancelAiBatchCmd.java | 70 +
.../ai/api/command/CheckAiHfModelCmd.java | 60 +
.../ai/api/command/CreateAiApiKeyCmd.java | 122 +
.../ai/api/command/CreateAiBatchCmd.java | 89 +
.../ai/api/command/CreateAiBudgetCmd.java | 107 +
.../command/CreateAiGenerationProfileCmd.java | 86 +
.../command/CreateAiGuardrailProfileCmd.java | 100 +
.../command/CreateAiPlaygroundSessionCmd.java | 79 +
.../command/CreateAiPrivateEndpointCmd.java | 119 +
.../command/CreateAiServingProfileCmd.java | 82 +
.../ai/api/command/DeleteAiAdapterCmd.java | 70 +
.../ai/api/command/DeleteAiBudgetCmd.java | 70 +
.../api/command/DeleteAiCertificateCmd.java | 70 +
.../command/DeleteAiGenerationProfileCmd.java | 70 +
.../command/DeleteAiGuardrailProfileCmd.java | 70 +
.../command/DeleteAiModelDeploymentCmd.java | 73 +
.../command/DeleteAiPrivateEndpointCmd.java | 69 +
.../command/DeleteAiServingProfileCmd.java | 69 +
.../ai/api/command/DeployAiModelCmd.java | 113 +
.../api/command/DiscoverAiGpuClassesCmd.java | 52 +
.../ai/api/command/DrainAiNodeCmd.java | 69 +
.../ai/api/command/GetAiBatchResultsCmd.java | 54 +
.../command/GetAiEffectiveParametersCmd.java | 58 +
.../ai/api/command/ListAiAdaptersCmd.java | 57 +
.../ai/api/command/ListAiApiKeysCmd.java | 52 +
.../ai/api/command/ListAiBatchesCmd.java | 57 +
.../ai/api/command/ListAiBudgetsCmd.java | 52 +
.../ai/api/command/ListAiCertificatesCmd.java | 57 +
.../ai/api/command/ListAiEndpointsCmd.java | 62 +
.../ai/api/command/ListAiEvaluationsCmd.java | 57 +
.../command/ListAiGenerationProfilesCmd.java | 57 +
.../ai/api/command/ListAiGpuCapacityCmd.java | 52 +
.../command/ListAiGuardrailProfilesCmd.java | 57 +
.../command/ListAiModelDeploymentsCmd.java | 57 +
.../ai/api/command/ListAiModelsCmd.java | 62 +
.../command/ListAiPrivateEndpointsCmd.java | 57 +
.../api/command/ListAiReconcilerRunsCmd.java | 57 +
.../api/command/ListAiServingProfilesCmd.java | 57 +
.../ai/api/command/ListAiSetupChecksCmd.java | 52 +
.../ai/api/command/ListAiUsageCmd.java | 73 +
.../ai/api/command/MirrorAiModelCmd.java | 70 +
.../ai/api/command/PromoteAiRolloutCmd.java | 64 +
.../ai/api/command/PublishAiModelCmd.java | 90 +
.../api/command/ReplaceAiCertificateCmd.java | 90 +
.../ai/api/command/RevokeAiApiKeyCmd.java | 70 +
.../ai/api/command/RollbackAiRolloutCmd.java | 64 +
.../api/command/RunAiModelEvaluationCmd.java | 79 +
.../ai/api/command/RunAiSetupSelfTestCmd.java | 75 +
.../ai/api/command/SearchAiHfModelsCmd.java | 63 +
.../ai/api/command/UpdateAiBudgetCmd.java | 97 +
.../command/UpdateAiGenerationProfileCmd.java | 83 +
.../command/UpdateAiGuardrailProfileCmd.java | 83 +
.../command/UpdateAiModelDeploymentCmd.java | 91 +
.../command/UpdateAiServingProfileCmd.java | 84 +
.../ai/api/command/UploadAiAdapterCmd.java | 118 +
.../api/command/UploadAiCertificateCmd.java | 93 +
.../ai/api/response/AiAdapterResponse.java | 156 ++
.../ai/api/response/AiApiKeyResponse.java | 114 +
.../ai/api/response/AiBatchResponse.java | 144 ++
.../ai/api/response/AiBudgetResponse.java | 150 ++
.../api/response/AiCertificateResponse.java | 126 +
.../ai/api/response/AiDeploymentResponse.java | 105 +
.../AiEffectiveParameterResponse.java | 118 +
.../ai/api/response/AiEndpointResponse.java | 118 +
.../ai/api/response/AiEvaluationResponse.java | 117 +
.../api/response/AiGpuCapacityResponse.java | 126 +
.../response/AiGpuClassProposalResponse.java | 90 +
.../response/AiGuardrailCheckResponse.java | 90 +
.../response/AiGuardrailProfileResponse.java | 122 +
.../ai/api/response/AiHfCheckResponse.java | 156 ++
.../ai/api/response/AiHfModelResponse.java | 99 +
.../ai/api/response/AiModelResponse.java | 118 +
.../response/AiPlaygroundSessionResponse.java | 105 +
.../response/AiPrivateEndpointResponse.java | 153 ++
.../ai/api/response/AiProfileResponse.java | 102 +
.../response/AiReconcilerActionResponse.java | 105 +
.../api/response/AiReconcilerRunResponse.java | 142 ++
.../ai/api/response/AiSetupCheckResponse.java | 93 +
.../ai/api/response/AiSnippetResponse.java | 89 +
.../ai/api/response/AiUsageResponse.java | 132 +
.../cloudstack/ai/dao/AiDeploymentDao.java | 41 +
.../ai/dao/AiDeploymentDaoImpl.java | 84 +
.../cloudstack/ai/dao/AiDeploymentVO.java | 143 ++
.../cloudstack/ai/engine/CallerContext.java | 128 +
.../cloudstack/ai/engine/EngineClient.java | 130 +
.../cloudstack/ai/engine/EngineException.java | 61 +
.../cloudstack/ai/engine/EngineJob.java | 114 +
.../cloudstack/ai/engine/EngineJobPoller.java | 108 +
.../cloudstack/ai/engine/EnginePaths.java | 39 +
.../cloudstack/ai/engine/EngineResponse.java | 84 +
.../cloudstack/ai/engine/EngineTransport.java | 32 +
.../ai/engine/HttpEngineTransport.java | 107 +
.../cloudstack/ai/engine/MutualTls.java | 125 +
.../ai/maintenance/AiMaintenanceListener.java | 133 ++
.../ai/maintenance/MaintenanceDrain.java | 119 +
.../cloudstack/ai-services/module.properties | 16 +
.../spring-ai-services-context.xml | 34 +
.../META-INF/db/schema-ai-services.sql | 50 +
.../ai/AiServicesCatalogueTest.java | 139 ++
.../cloudstack/ai/AiServicesConfigTest.java | 151 ++
.../ai/AiServicesManagerImplTest.java | 162 ++
.../cloudstack/ai/AiServicesSchemaTest.java | 215 ++
.../ai/CommandRegistrationTest.java | 189 ++
.../cloudstack/ai/GeneratedSurfaceTest.java | 291 +++
.../cloudstack/ai/SpringContextTest.java | 129 +
.../ai/V2CommandRegistrationTest.java | 124 +
.../ai/api/command/AiCommandsTest.java | 221 ++
.../api/command/AiServicesAsyncCmdTest.java | 201 ++
.../ai/api/command/AiServicesSyncCmdTest.java | 318 +++
.../ai/api/command/EventRecordingTest.java | 264 ++
.../command/PrivateEndpointNetworkTest.java | 129 +
.../ai/api/response/AiApiKeyResponseTest.java | 69 +
.../ai/api/response/AiModelResponseTest.java | 120 +
.../ai/engine/CallerContextTest.java | 97 +
.../ai/engine/EngineClientTest.java | 219 ++
.../ai/engine/EngineJobPollerTest.java | 156 ++
.../cloudstack/ai/engine/EngineJobTest.java | 115 +
.../ai/engine/HttpEngineTransportTest.java | 218 ++
.../cloudstack/ai/engine/MutualTlsTest.java | 86 +
.../cloudstack/ai/engine/TrustStoreTest.java | 84 +
.../AiMaintenanceListenerTest.java | 139 ++
.../ai/maintenance/MaintenanceDrainTest.java | 170 ++
.../resources/generated-engine-objects.json | 180 ++
.../ai-services/tools/generate_commands.py | 2113 +++++++++++++++++
plugins/pom.xml | 1 +
ui/public/locales/en.json | 152 +-
ui/src/config/router.js | 2 +
ui/src/config/section/aiservices.js | 845 +++++++
ui/src/utils/capacity.js | 92 +
ui/src/utils/errors.js | 44 +
ui/src/utils/profiles.js | 50 +
ui/src/utils/setup.js | 42 +
ui/src/views/aiservices/ApiKeysTab.vue | 193 ++
ui/src/views/aiservices/BudgetsTab.vue | 113 +
.../views/aiservices/EffectiveParameters.vue | 119 +
ui/src/views/aiservices/EvaluationsTab.vue | 112 +
ui/src/views/aiservices/FleetHealth.vue | 102 +
ui/src/views/aiservices/GpuCapacity.vue | 99 +
.../views/aiservices/GuardrailChecksTab.vue | 66 +
.../views/aiservices/HuggingFaceBrowser.vue | 108 +
ui/src/views/aiservices/Playground.vue | 144 ++
ui/src/views/aiservices/RunActionsTab.vue | 82 +
ui/src/views/aiservices/SetupWizard.vue | 106 +
ui/src/views/aiservices/SnippetsTab.vue | 54 +
158 files changed, 19243 insertions(+), 1 deletion(-)
create mode 100644 plugins/api/ai-services/README.md
create mode 100644 plugins/api/ai-services/pom.xml
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesConfig.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesEvents.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesManagerImpl.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesSchema.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesService.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesUsageTypes.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesListCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ApproveAiModelCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AssignAiTuningProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CancelAiBatchCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CheckAiHfModelCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiApiKeyCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBatchCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBudgetCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGenerationProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGuardrailProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPlaygroundSessionCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPrivateEndpointCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiServingProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiAdapterCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiBudgetCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiCertificateCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGenerationProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGuardrailProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiModelDeploymentCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiPrivateEndpointCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiServingProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeployAiModelCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DiscoverAiGpuClassesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DrainAiNodeCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiBatchResultsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiEffectiveParametersCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiAdaptersCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiApiKeysCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBatchesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBudgetsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiCertificatesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEndpointsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEvaluationsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGenerationProfilesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGpuCapacityCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGuardrailProfilesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelDeploymentsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiPrivateEndpointsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiReconcilerRunsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiServingProfilesCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiSetupChecksCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiUsageCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/MirrorAiModelCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PromoteAiRolloutCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PublishAiModelCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ReplaceAiCertificateCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RevokeAiApiKeyCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RollbackAiRolloutCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiModelEvaluationCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiSetupSelfTestCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/SearchAiHfModelsCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiBudgetCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGenerationProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGuardrailProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiModelDeploymentCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiServingProfileCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiAdapterCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiCertificateCmd.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiAdapterResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBatchResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBudgetResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiCertificateResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiDeploymentResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEffectiveParameterResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEndpointResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEvaluationResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuCapacityResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuClassProposalResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailCheckResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailProfileResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfCheckResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfModelResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiModelResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPlaygroundSessionResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPrivateEndpointResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiProfileResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerActionResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerRunResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSetupCheckResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSnippetResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiUsageResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDao.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDaoImpl.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentVO.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/CallerContext.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineClient.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineException.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJob.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJobPoller.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EnginePaths.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineResponse.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineTransport.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/HttpEngineTransport.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/MutualTls.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListener.java
create mode 100644 plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrain.java
create mode 100644 plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/module.properties
create mode 100644 plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/spring-ai-services-context.xml
create mode 100644 plugins/api/ai-services/src/main/resources/META-INF/db/schema-ai-services.sql
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesCatalogueTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesConfigTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesManagerImplTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesSchemaTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/CommandRegistrationTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/GeneratedSurfaceTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/SpringContextTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/V2CommandRegistrationTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiCommandsTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmdTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmdTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/EventRecordingTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/PrivateEndpointNetworkTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponseTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiModelResponseTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/CallerContextTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineClientTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobPollerTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/HttpEngineTransportTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/MutualTlsTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/TrustStoreTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListenerTest.java
create mode 100644 plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrainTest.java
create mode 100644 plugins/api/ai-services/src/test/resources/generated-engine-objects.json
create mode 100644 plugins/api/ai-services/tools/generate_commands.py
create mode 100644 ui/src/config/section/aiservices.js
create mode 100644 ui/src/utils/capacity.js
create mode 100644 ui/src/utils/errors.js
create mode 100644 ui/src/utils/profiles.js
create mode 100644 ui/src/utils/setup.js
create mode 100644 ui/src/views/aiservices/ApiKeysTab.vue
create mode 100644 ui/src/views/aiservices/BudgetsTab.vue
create mode 100644 ui/src/views/aiservices/EffectiveParameters.vue
create mode 100644 ui/src/views/aiservices/EvaluationsTab.vue
create mode 100644 ui/src/views/aiservices/FleetHealth.vue
create mode 100644 ui/src/views/aiservices/GpuCapacity.vue
create mode 100644 ui/src/views/aiservices/GuardrailChecksTab.vue
create mode 100644 ui/src/views/aiservices/HuggingFaceBrowser.vue
create mode 100644 ui/src/views/aiservices/Playground.vue
create mode 100644 ui/src/views/aiservices/RunActionsTab.vue
create mode 100644 ui/src/views/aiservices/SetupWizard.vue
create mode 100644 ui/src/views/aiservices/SnippetsTab.vue
diff --git a/client/pom.xml b/client/pom.xml
index cc031a4912b1..a9014fd22902 100644
--- a/client/pom.xml
+++ b/client/pom.xml
@@ -201,6 +201,11 @@
cloud-plugin-api-limit-account-based${project.version}
+
+ org.apache.cloudstack
+ cloud-plugin-api-ai-services
+ ${project.version}
+ org.apache.cloudstackcloud-plugin-api-discovery
diff --git a/plugins/api/ai-services/README.md b/plugins/api/ai-services/README.md
new file mode 100644
index 000000000000..2014a15d94b4
--- /dev/null
+++ b/plugins/api/ai-services/README.md
@@ -0,0 +1,139 @@
+
+
+# cloud-plugin-api-ai-services
+
+> **This plugin is developed out of tree, at
+> [kiwiflyer/CloudStack_AI_Plugin](https://github.com/kiwiflyer/CloudStack_AI_Plugin).**
+>
+> That repository holds the whole product: this Java plugin, the Python
+> engine it talks to over mTLS, the `aiservices` UI section, the
+> Terraform provider, the Marvin tests and the specification the command
+> map is generated from. **Change it there, not here** — the commands,
+> their parameters and their default role grants are generated from
+> `aisvc/api/commands.py`, and drift between the two is what the tests
+> in that repository exist to catch.
+>
+> The branch this file is on carries only the two pieces that have to
+> live inside CloudStack's own tree: this plugin and the UI section.
+> See [the branch note](../../../AI-SERVICES-BRANCH.md) for what was
+> copied, what was changed to make it build here, and what has not been
+> verified against this version of CloudStack.
+
+Building and deploying this is one part of standing the product up; see
+[docs/installation.md](https://github.com/kiwiflyer/CloudStack_AI_Plugin/blob/main/docs/installation.md) for the whole sequence.
+
+The native CloudStack API plugin (SPEC.md section 9), targeting
+**CloudStack 4.23.0.0** ([ADR-0003](https://github.com/kiwiflyer/CloudStack_AI_Plugin/blob/main/docs/adr/0003-cloudstack-release.md)).
+
+It has been loaded into a real 4.23.0.0 management server: all 38 v1
+commands register (`listApis` 865 → 903), twenty more with
+`ai.services.v2.enabled` on, the `ai_deployment` table is created at
+startup, the ten `ai.services.*` settings appear in
+`listConfigurations`, and commands answer with data from the engine
+over mTLS. The per-role Marvin tests in
+[`test/integration/plugins/ai-services/`](https://github.com/kiwiflyer/CloudStack_AI_Plugin/tree/main/test/integration/plugins/ai-services/)
+cover all 58 commands, allowed and denied, and pass.
+
+**Loading it is how the defects were found.** A Spring context that
+did not declare a bean it injected took the whole `/client` webapp
+down, not just the plugin; seven write commands sent request bodies
+missing exactly the parameters whose names needed no translation; a
+PEM parameter was capped at `@Parameter`'s default 255 characters;
+and both the sync and async paths threw away the engine's explanation
+of a failure. Every one compiled and passed its unit tests.
+
+## Building
+
+CloudStack publishes **no Maven artifacts** — not to Maven Central, not to the ASF
+repositories. The dependencies must be built from source into your local repository first:
+
+```bash
+git clone --depth 1 --branch 4.23.0.0 --single-branch https://github.com/apache/cloudstack.git
+```
+
+```bash
+cd cloudstack && mvn install -DskipTests -Dcheckstyle.skip -Dlicense.skip -Drat.skip -pl api,utils,framework/config,framework/db,framework/events,engine/schema -am
+```
+
+Then, from the repository root:
+
+```bash
+make test-java
+```
+
+Needs JDK 17 to build (`brew install openjdk@17 maven`); it targets JDK 11 bytecode, which is
+what CloudStack 4.23 sets as `cs.jdk.version`. `openjdk@17` is keg-only, so set
+`JAVA_HOME=/opt/homebrew/opt/openjdk@17`.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| `AiServicesConfig` | The ConfigKeys of section 9. Enablement is zone-scoped, Hugging Face approval domain-scoped |
+| `AiServicesService` / `AiServicesManagerImpl` | The `PluggableService` and `Configurable` entry point |
+| `engine/EngineClient` | Calls the engine, failing over across replicas |
+| `engine/HttpEngineTransport`, `engine/MutualTls` | The mTLS transport |
+| `engine/CallerContext` | The identity the engine filters every response by |
+| `api/command/`, `api/response/` | API commands and their responses |
+| `META-INF/db/schema-ai-services.sql` | The `ai_deployment` ownership table |
+
+## Generated code
+
+Thirty-six of the thirty-eight v1 commands, the twenty v2 ones, and twenty-one
+response types differ only in name, verb, engine path, parameters and response shape.
+(`deployAiModel` and `deleteAiModelDeployment` are the two written by hand: they own
+the `ai_deployment` row CloudStack uses for ownership and cleanup, which the generator
+does not model.) Writing them out by hand invites the one transposed path or
+wrong role no reviewer would spot, so the leaves are generated:
+
+```bash
+python3 tools/generate_commands.py
+```
+
+Generated files say so in their header. **Edit `tools/generate_commands.py`, not them.** The
+interesting parts — the base classes, the engine client, the async bridge, the DAO — are
+hand-written.
+
+The generator also emits `src/test/resources/generated-engine-objects.json`, a fully-populated
+engine object per response type, so `GeneratedSurfaceTest` exercises every mapped field
+without that list being maintained twice.
+
+## The 4.22 LTS floor
+
+[ADR-0003](https://github.com/kiwiflyer/CloudStack_AI_Plugin/blob/main/docs/adr/0003-cloudstack-release.md) targets 4.23, which is **non-LTS**. The
+plugin is held to APIs that also exist in 4.22 LTS so the eventual retarget costs a rebuild
+rather than a rewrite. Verify locally by building 4.22's modules the same way and then:
+
+```bash
+mvn -Dcs.version=4.22.1.1 test
+```
+
+CI runs this on every change.
+
+## Two rules worth keeping
+
+**The caller context is built from `CallContext`, never from request parameters.** The engine
+authenticates nobody — it is unreachable from tenant networks and requires a client
+certificate — and filters every response by what this plugin asserts. A caller able to
+influence it could read another tenant's data.
+
+**The command list is generated, not hand-written.** `aisvc/api/commands.py` holds section 9's
+map, and the Python tests check it against the engine's routes. Adding a command there and
+forgetting it here should be caught by a test, not by a Marvin run.
diff --git a/plugins/api/ai-services/pom.xml b/plugins/api/ai-services/pom.xml
new file mode 100644
index 000000000000..2515a9301bdb
--- /dev/null
+++ b/plugins/api/ai-services/pom.xml
@@ -0,0 +1,122 @@
+
+
+ 4.0.0
+ Apache CloudStack Plugin - AI Services
+ cloud-plugin-api-ai-services
+
+ cloudstack-plugins
+ org.apache.cloudstack
+ 24.0.0-SNAPSHOT
+ ../../pom.xml
+
+
+
+
+
+ org.apache.cloudstack
+ cloud-api
+ ${project.version}
+
+
+ org.apache.cloudstack
+ cloud-utils
+ ${project.version}
+
+
+ org.apache.cloudstack
+ cloud-framework-config
+ ${project.version}
+
+
+ org.apache.cloudstack
+ cloud-framework-db
+ ${project.version}
+
+
+ org.apache.cloudstack
+ cloud-framework-events
+ ${project.version}
+
+
+ org.apache.cloudstack
+ cloud-engine-schema
+ ${project.version}
+
+
+
+
+ org.junit.jupiter
+ junit-jupiter
+ ${cs.junit.jupiter.version}
+ test
+
+
+ org.junit.jupiter
+ junit-jupiter-params
+ ${cs.junit.jupiter.version}
+ test
+
+
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-surefire-plugin
+ ${cs.surefire-plugin.version}
+
+
+ org.apache.maven.surefire
+ surefire-junit-platform
+ ${cs.surefire-plugin.version}
+
+
+
+
+
+
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesConfig.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesConfig.java
new file mode 100644
index 000000000000..bed6853e3b0a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesConfig.java
@@ -0,0 +1,134 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import org.apache.cloudstack.framework.config.ConfigKey;
+
+/**
+ * Global settings for the AI Services plugin (SPEC.md section 9).
+ *
+ * Scopes matter here: enablement is per zone because a provider may run
+ * GPU capacity in one zone only, and Hugging Face approval is per domain
+ * because section 5 lets a reseller mirror directly while others must
+ * request it.
+ */
+public final class AiServicesConfig {
+
+ private AiServicesConfig() {
+ }
+
+ private static final String CATEGORY = "Advanced";
+
+ /**
+ * The category CloudStack encrypts.
+ *
+ *
{@code ConfigurationVO.isEncrypted()} is a literal
+ * {@code StringUtils.equalsAny(getCategory(), "Hidden", "Secure")},
+ * so a password declared anywhere else is stored in the database —
+ * and returned by {@code listConfigurations} — in cleartext.
+ * "Secure" rather than "Hidden" because an operator still has to
+ * find the setting to fill it in.
+ */
+ private static final String SECRET_CATEGORY = "Secure";
+
+ public static final ConfigKey Enabled = new ConfigKey<>(
+ CATEGORY, Boolean.class, "ai.services.enabled", "false",
+ "Whether AI Services is enabled in this zone.", true, ConfigKey.Scope.Zone);
+
+ /**
+ * Comma-separated engine URLs. More than one because the engine runs at
+ * least two replicas behind a load balancer and the plugin fails over
+ * between them (SPEC.md section 7).
+ */
+ public static final ConfigKey EngineUrls = new ConfigKey<>(
+ CATEGORY, String.class, "ai.services.engine.urls", "",
+ "Comma-separated base URLs of the AI Services engine API, tried in order.",
+ true, ConfigKey.Scope.Global);
+
+ public static final ConfigKey EngineTimeout = new ConfigKey<>(
+ CATEGORY, Integer.class, "ai.services.engine.timeout", "30",
+ "Seconds to wait for an engine API response before failing over.",
+ true, ConfigKey.Scope.Global);
+
+ public static final ConfigKey EngineClientCert = new ConfigKey<>(
+ CATEGORY, String.class, "ai.services.engine.tls.client.cert", "",
+ "Path to the PKCS12 key store holding the client certificate and key "
+ + "the plugin presents to the engine (mTLS).",
+ true, ConfigKey.Scope.Global);
+
+ public static final ConfigKey EngineClientKey = new ConfigKey<>(
+ SECRET_CATEGORY, String.class, "ai.services.engine.tls.client.key", "",
+ "Password for that key store. Not a path — the description said one "
+ + "for a while, and the code has always read it as a password.",
+ true, ConfigKey.Scope.Global);
+
+ public static final ConfigKey EngineTrustStore = new ConfigKey<>(
+ CATEGORY, String.class, "ai.services.engine.tls.truststore", "",
+ "Path to the PKCS12 trust store holding the engine's CA certificate.",
+ true, ConfigKey.Scope.Global);
+
+ public static final ConfigKey EngineTrustStorePassword = new ConfigKey<>(
+ CATEGORY, String.class, "ai.services.engine.tls.truststore.password", "changeit",
+ "Password for the trust store. It needs one: keytool refuses a password "
+ + "under six characters, and a store openssl writes with an empty "
+ + "password loads as zero certificates rather than failing.",
+ true, ConfigKey.Scope.Global);
+
+ /**
+ * Domain-scoped: where false, a domain admin may mirror from Hugging Face
+ * directly; where true, their request goes to a root admin queue
+ * (SPEC.md section 5, step 4).
+ */
+ public static final ConfigKey HfRequireApproval = new ConfigKey<>(
+ CATEGORY, Boolean.class, "ai.services.hf.require.approval", "true",
+ "Whether domain admin mirror requests need root admin approval.",
+ true, ConfigKey.Scope.Domain);
+
+ /**
+ * How long host maintenance waits for a drain before the admin must
+ * confirm a forced drain (SPEC.md section 7).
+ */
+ public static final ConfigKey MaintenanceDrainTimeout = new ConfigKey<>(
+ CATEGORY, Integer.class, "ai.services.maintenance.drain.timeout", "900",
+ "Seconds to wait for GPU nodes to drain before a host enters maintenance.",
+ true, ConfigKey.Scope.Global);
+
+ /**
+ * Whether the Tier 2 command surface is registered (SPEC.md section 8).
+ *
+ *
Off by default. The engine marks these {@code Release.V2}, and a
+ * GA install should not grow a surface for features it does not run;
+ * this is how the same boundary holds on the plugin side.
+ */
+ public static final ConfigKey V2Enabled = new ConfigKey<>(
+ CATEGORY, Boolean.class, "ai.services.v2.enabled", "false",
+ "Register the Tier 2 (v2) AI Services API commands.",
+ true, ConfigKey.Scope.Global);
+
+ public static ConfigKey>[] all() {
+ return new ConfigKey>[] {
+ Enabled,
+ EngineUrls,
+ EngineTimeout,
+ EngineClientCert,
+ EngineClientKey,
+ EngineTrustStore,
+ EngineTrustStorePassword,
+ HfRequireApproval,
+ MaintenanceDrainTimeout,
+ V2Enabled,
+ };
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesEvents.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesEvents.java
new file mode 100644
index 000000000000..37740f2c5780
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesEvents.java
@@ -0,0 +1,88 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+/**
+ * Action event types (SPEC.md section 9).
+ *
+ * Every state change appears in CloudStack's event stream, which is what
+ * section 14 means by "every action appears in CloudStack events". These
+ * follow CloudStack's own dotted convention so existing event consumers
+ * and alerting need no special handling.
+ */
+public final class AiServicesEvents {
+
+ private AiServicesEvents() {
+ }
+
+ public static final String MODEL_MIRROR = "AI.MODEL.MIRROR";
+ public static final String MODEL_PUBLISH = "AI.MODEL.PUBLISH";
+ public static final String MODEL_DEPLOY = "AI.MODEL.DEPLOY";
+ public static final String MODEL_UPDATE = "AI.MODEL.UPDATE";
+ public static final String MODEL_DELETE = "AI.MODEL.DELETE";
+ public static final String ROLLOUT_PROMOTE = "AI.ROLLOUT.PROMOTE";
+ public static final String ROLLOUT_ROLLBACK = "AI.ROLLOUT.ROLLBACK";
+ public static final String PROFILE_UPDATE = "AI.PROFILE.UPDATE";
+ public static final String KEY_CREATE = "AI.KEY.CREATE";
+ public static final String KEY_REVOKE = "AI.KEY.REVOKE";
+ public static final String BUDGET_THRESHOLD = "AI.BUDGET.THRESHOLD";
+ public static final String NODE_DRAIN = "AI.NODE.DRAIN";
+ /**
+ * Setting a budget, as against crossing one.
+ *
+ * BUDGET_THRESHOLD is an alert raised by spend; this is the
+ * operator action that decided what the limit is, and an audit of
+ * "who raised this account's ceiling" needs the second, not the
+ * first.
+ */
+ public static final String BUDGET_UPDATE = "AI.BUDGET.UPDATE";
+ /**
+ * A playground session, which mints a key that expires in fifteen
+ * minutes. Short-lived is not the same as unaudited: it is still a
+ * credential against a model, issued to someone.
+ */
+ public static final String PLAYGROUND_SESSION = "AI.PLAYGROUND.SESSION";
+
+ // Tier 2 (SPEC.md section 8).
+ public static final String ADAPTER_UPLOAD = "AI.ADAPTER.UPLOAD";
+ public static final String ADAPTER_DELETE = "AI.ADAPTER.DELETE";
+ public static final String BATCH_CREATE = "AI.BATCH.CREATE";
+ public static final String BATCH_CANCEL = "AI.BATCH.CANCEL";
+ /** v2, with the guardrail profiles of section 8. */
+ public static final String GUARDRAIL_BLOCK = "AI.GUARDRAIL.BLOCK";
+ public static final String CERTIFICATE_UPLOAD = "AI.CERTIFICATE.UPLOAD";
+ /**
+ * Replacing a certificate, which is not an edit: a proxy reads its
+ * TLS material once at boot, so a replacement replaces the proxy VM
+ * and the endpoint goes down with it (CLAUDE.md). An operator
+ * reading the log should see that as its own action.
+ */
+ public static final String CERTIFICATE_REPLACE = "AI.CERTIFICATE.REPLACE";
+ public static final String CERTIFICATE_DELETE = "AI.CERTIFICATE.DELETE";
+
+ public static String[] all() {
+ return new String[] {
+ MODEL_MIRROR, MODEL_PUBLISH, MODEL_DEPLOY, MODEL_UPDATE, MODEL_DELETE,
+ ROLLOUT_PROMOTE, ROLLOUT_ROLLBACK, PROFILE_UPDATE, KEY_CREATE,
+ KEY_REVOKE, BUDGET_THRESHOLD, BUDGET_UPDATE, PLAYGROUND_SESSION,
+ NODE_DRAIN, GUARDRAIL_BLOCK,
+ // v2. These were defined but left out of all(), so
+ // nothing that walks this list — the convention and
+ // uniqueness checks included — ever saw them.
+ ADAPTER_UPLOAD, ADAPTER_DELETE, BATCH_CREATE, BATCH_CANCEL,
+ CERTIFICATE_UPLOAD, CERTIFICATE_REPLACE, CERTIFICATE_DELETE,
+ };
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesManagerImpl.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesManagerImpl.java
new file mode 100644
index 000000000000..ca095e0d5625
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesManagerImpl.java
@@ -0,0 +1,527 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import javax.inject.Inject;
+import com.cloud.event.ActionEvent;
+import com.cloud.host.HostVO;
+import com.cloud.host.dao.HostDao;
+import com.cloud.vm.VMInstanceVO;
+import com.cloud.vm.dao.VMInstanceDao;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.ai.engine.EngineJobPoller;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.ai.engine.EngineException;
+import org.apache.cloudstack.ai.maintenance.AiMaintenanceListener;
+import org.apache.cloudstack.ai.maintenance.MaintenanceDrain;
+import org.apache.cloudstack.framework.events.EventBus;
+import org.springframework.beans.factory.NoSuchBeanDefinitionException;
+import com.cloud.utils.component.ComponentContext;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.ai.engine.EngineClient;
+import org.apache.cloudstack.ai.api.command.ApproveAiModelCmd;
+import org.apache.cloudstack.ai.api.command.AssignAiTuningProfileCmd;
+import org.apache.cloudstack.ai.api.command.CancelAiBatchCmd;
+import org.apache.cloudstack.ai.api.command.CheckAiHfModelCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiApiKeyCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiBatchCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiBudgetCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiGenerationProfileCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiGuardrailProfileCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiPlaygroundSessionCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiPrivateEndpointCmd;
+import org.apache.cloudstack.ai.api.command.CreateAiServingProfileCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiAdapterCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiBudgetCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiCertificateCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiGenerationProfileCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiGuardrailProfileCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiModelDeploymentCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiPrivateEndpointCmd;
+import org.apache.cloudstack.ai.api.command.DeleteAiServingProfileCmd;
+import org.apache.cloudstack.ai.api.command.DeployAiModelCmd;
+import org.apache.cloudstack.ai.api.command.DiscoverAiGpuClassesCmd;
+import org.apache.cloudstack.ai.api.command.DrainAiNodeCmd;
+import org.apache.cloudstack.ai.api.command.GetAiBatchResultsCmd;
+import org.apache.cloudstack.ai.api.command.GetAiEffectiveParametersCmd;
+import org.apache.cloudstack.ai.api.command.ListAiAdaptersCmd;
+import org.apache.cloudstack.ai.api.command.ListAiApiKeysCmd;
+import org.apache.cloudstack.ai.api.command.ListAiBatchesCmd;
+import org.apache.cloudstack.ai.api.command.ListAiBudgetsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiCertificatesCmd;
+import org.apache.cloudstack.ai.api.command.ListAiEndpointsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiEvaluationsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiGenerationProfilesCmd;
+import org.apache.cloudstack.ai.api.command.ListAiGpuCapacityCmd;
+import org.apache.cloudstack.ai.api.command.ListAiGuardrailProfilesCmd;
+import org.apache.cloudstack.ai.api.command.ListAiModelDeploymentsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiPrivateEndpointsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiModelsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiReconcilerRunsCmd;
+import org.apache.cloudstack.ai.api.command.ListAiServingProfilesCmd;
+import org.apache.cloudstack.ai.api.command.ListAiSetupChecksCmd;
+import org.apache.cloudstack.ai.api.command.ListAiUsageCmd;
+import org.apache.cloudstack.ai.api.command.MirrorAiModelCmd;
+import org.apache.cloudstack.ai.api.command.PromoteAiRolloutCmd;
+import org.apache.cloudstack.ai.api.command.PublishAiModelCmd;
+import org.apache.cloudstack.ai.api.command.ReplaceAiCertificateCmd;
+import org.apache.cloudstack.ai.api.command.RevokeAiApiKeyCmd;
+import org.apache.cloudstack.ai.api.command.RollbackAiRolloutCmd;
+import org.apache.cloudstack.ai.api.command.RunAiModelEvaluationCmd;
+import org.apache.cloudstack.ai.api.command.RunAiSetupSelfTestCmd;
+import org.apache.cloudstack.ai.api.command.SearchAiHfModelsCmd;
+import org.apache.cloudstack.ai.api.command.UpdateAiBudgetCmd;
+import org.apache.cloudstack.ai.api.command.UpdateAiGenerationProfileCmd;
+import org.apache.cloudstack.ai.api.command.UpdateAiGuardrailProfileCmd;
+import org.apache.cloudstack.ai.api.command.UpdateAiModelDeploymentCmd;
+import org.apache.cloudstack.ai.api.command.UpdateAiServingProfileCmd;
+import org.apache.cloudstack.ai.api.command.UploadAiAdapterCmd;
+import org.apache.cloudstack.ai.api.command.UploadAiCertificateCmd;
+import org.apache.cloudstack.ai.dao.AiDeploymentDao;
+import org.apache.cloudstack.ai.engine.EngineTransport;
+import org.apache.cloudstack.ai.engine.HttpEngineTransport;
+import org.apache.cloudstack.context.CallContext;
+import org.apache.cloudstack.framework.config.ConfigKey;
+import org.apache.cloudstack.framework.config.Configurable;
+
+import com.cloud.domain.Domain;
+import com.cloud.domain.dao.DomainDao;
+import com.cloud.user.Account;
+import com.cloud.user.User;
+import com.cloud.utils.component.ManagerBase;
+
+/**
+ * Registers the plugin's commands and configuration (SPEC.md section 9).
+ *
+ * The command list is generated from the engine's command map
+ * (aisvc/api/commands.py) rather than maintained here by hand, so a
+ * command cannot exist on one side and be missing from the other.
+ */
+public class AiServicesManagerImpl extends ManagerBase
+ implements AiServicesService, Configurable {
+
+ @Inject
+ private DomainDao domainDao;
+
+ @Inject
+ private AiDeploymentDao deploymentDao;
+
+ private static final Logger LOG = LogManager.getLogger(AiServicesManagerImpl.class);
+
+ /** GPU node VMs are named aisvc-- (CLAUDE.md). */
+ static final String NODE_NAME_PREFIX = "aisvc-";
+
+ @Inject
+ private VMInstanceDao vmInstanceDao;
+
+ @Inject
+ private HostDao hostDao;
+
+ private AiMaintenanceListener maintenanceListener;
+
+ private EngineClient engineClient;
+ private EngineTransport transport;
+
+ @Override
+ public List> getCommands() {
+ List> commands = new ArrayList<>();
+ // Every v1 command from SPEC.md section 9. The list is kept in
+ // step with the engine's routes by aisvc/api/commands.py and the
+ // tests on both sides.
+ commands.add(ApproveAiModelCmd.class);
+ commands.add(AssignAiTuningProfileCmd.class);
+ commands.add(CheckAiHfModelCmd.class);
+ commands.add(CreateAiApiKeyCmd.class);
+ commands.add(CreateAiBudgetCmd.class);
+ commands.add(CreateAiGenerationProfileCmd.class);
+ commands.add(CreateAiPlaygroundSessionCmd.class);
+ commands.add(CreateAiServingProfileCmd.class);
+ commands.add(DeleteAiBudgetCmd.class);
+ commands.add(DeleteAiGenerationProfileCmd.class);
+ commands.add(DeleteAiModelDeploymentCmd.class);
+ commands.add(DeleteAiServingProfileCmd.class);
+ commands.add(DeployAiModelCmd.class);
+ commands.add(DiscoverAiGpuClassesCmd.class);
+ commands.add(DrainAiNodeCmd.class);
+ commands.add(GetAiEffectiveParametersCmd.class);
+ commands.add(ListAiApiKeysCmd.class);
+ commands.add(ListAiBudgetsCmd.class);
+ commands.add(ListAiEndpointsCmd.class);
+ commands.add(ListAiGenerationProfilesCmd.class);
+ commands.add(ListAiGpuCapacityCmd.class);
+ commands.add(ListAiModelDeploymentsCmd.class);
+ commands.add(ListAiModelsCmd.class);
+ commands.add(ListAiReconcilerRunsCmd.class);
+ commands.add(ListAiServingProfilesCmd.class);
+ commands.add(ListAiSetupChecksCmd.class);
+ commands.add(ListAiUsageCmd.class);
+ commands.add(MirrorAiModelCmd.class);
+ commands.add(PromoteAiRolloutCmd.class);
+ commands.add(PublishAiModelCmd.class);
+ commands.add(RevokeAiApiKeyCmd.class);
+ commands.add(RollbackAiRolloutCmd.class);
+ commands.add(RunAiSetupSelfTestCmd.class);
+ commands.add(SearchAiHfModelsCmd.class);
+ commands.add(UpdateAiBudgetCmd.class);
+ commands.add(UpdateAiGenerationProfileCmd.class);
+ commands.add(UpdateAiModelDeploymentCmd.class);
+ commands.add(UpdateAiServingProfileCmd.class);
+ if (v2Enabled()) {
+ commands.addAll(v2Commands());
+ }
+ return commands;
+ }
+
+ /**
+ * Whether to register the Tier 2 command surface.
+ *
+ *
Its own method so the split can be tested without a
+ * ConfigDepot; in production this is the global setting, which
+ * reads false when nothing has set it.
+ */
+ boolean v2Enabled() {
+ return AiServicesConfig.V2Enabled.value();
+ }
+
+ /**
+ * The Tier 2 commands (SPEC.md section 8).
+ *
+ *
Generated like the rest, but held back: the engine marks them
+ * {@code Release.V2}, and a GA install should not advertise an API
+ * for features it does not run. An operator turns them on with
+ * {@code ai.services.v2.enabled}.
+ */
+ private static List> v2Commands() {
+ List> commands = new ArrayList<>();
+ commands.add(CancelAiBatchCmd.class);
+ commands.add(CreateAiBatchCmd.class);
+ commands.add(CreateAiGuardrailProfileCmd.class);
+ commands.add(CreateAiPrivateEndpointCmd.class);
+ commands.add(DeleteAiAdapterCmd.class);
+ commands.add(DeleteAiCertificateCmd.class);
+ commands.add(DeleteAiGuardrailProfileCmd.class);
+ commands.add(DeleteAiPrivateEndpointCmd.class);
+ commands.add(GetAiBatchResultsCmd.class);
+ commands.add(ListAiAdaptersCmd.class);
+ commands.add(ListAiBatchesCmd.class);
+ commands.add(ListAiCertificatesCmd.class);
+ commands.add(ListAiEvaluationsCmd.class);
+ commands.add(ListAiGuardrailProfilesCmd.class);
+ commands.add(ListAiPrivateEndpointsCmd.class);
+ commands.add(ReplaceAiCertificateCmd.class);
+ commands.add(RunAiModelEvaluationCmd.class);
+ commands.add(UpdateAiGuardrailProfileCmd.class);
+ commands.add(UploadAiAdapterCmd.class);
+ commands.add(UploadAiCertificateCmd.class);
+ return commands;
+ }
+
+ @Override
+ public String getConfigComponentName() {
+ return AiServicesManagerImpl.class.getSimpleName();
+ }
+
+ @Override
+ public ConfigKey>[] getConfigKeys() {
+ return AiServicesConfig.all();
+ }
+
+ @Override
+ public boolean isEnabledInZone(long zoneId) {
+ return Boolean.TRUE.equals(AiServicesConfig.Enabled.valueIn(zoneId));
+ }
+
+ @Override
+ public synchronized EngineClient getEngineClient() {
+ if (engineClient == null) {
+ List urls = EngineClient.parseUrls(AiServicesConfig.EngineUrls.value());
+ engineClient = new EngineClient(urls, resolveTransport());
+ }
+ return engineClient;
+ }
+
+ private EngineTransport resolveTransport() {
+ if (transport != null) {
+ return transport;
+ }
+ return new HttpEngineTransport(
+ AiServicesConfig.EngineTimeout.value(),
+ AiServicesConfig.EngineClientCert.value(),
+ AiServicesConfig.EngineClientKey.value(),
+ AiServicesConfig.EngineTrustStore.value(),
+ AiServicesConfig.EngineTrustStorePassword.value());
+ }
+
+ /** Injection point for tests; production uses the mTLS transport. */
+ public synchronized void setTransport(EngineTransport transport) {
+ this.transport = transport;
+ this.engineClient = null;
+ }
+
+ /**
+ * Build the caller context from the CloudStack session.
+ *
+ * Never from request parameters: the engine trusts this assertion and
+ * filters every response by it, so a caller able to influence it could
+ * read another tenant's data.
+ */
+ @Override
+ public CallerContext currentCaller() {
+ CallContext context = CallContext.current();
+ if (context == null) {
+ throw new IllegalStateException("no CloudStack call context on this thread");
+ }
+ Account account = context.getCallingAccount();
+ User user = context.getCallingUser();
+ return new CallerContext(
+ String.valueOf(user.getUuid()),
+ account.getAccountName(),
+ domainPathOf(account.getDomainId()),
+ roleNameOf(account));
+ }
+
+ /**
+ * The caller's full domain path, for example /Customers/Acme.
+ *
+ * The engine decides domain-admin visibility by prefix-matching this
+ * against a resource's domain, so a wrong or partial path either
+ * hides a domain's own resources or exposes a sibling's. Resolved
+ * from the domain DAO rather than assembled from an id.
+ */
+ String domainPathOf(long domainId) {
+ Domain domain = domainDao == null ? null : domainDao.findById(domainId);
+ if (domain == null || domain.getPath() == null || domain.getPath().isEmpty()) {
+ throw new IllegalStateException(
+ "cannot resolve the path of domain " + domainId
+ + "; refusing to call the engine with an unknown domain");
+ }
+ String path = domain.getPath();
+ if (!path.startsWith("/")) {
+ path = "/" + path;
+ }
+ // CloudStack stores paths with a trailing slash; the engine
+ // compares them as prefixes, where a trailing slash would make
+ // /Customers/Acme/ fail to match /Customers/Acme.
+ return path.length() > 1 && path.endsWith("/")
+ ? path.substring(0, path.length() - 1)
+ : path;
+ }
+
+ private String roleNameOf(Account account) {
+ switch (account.getType()) {
+ case ADMIN:
+ return "Admin";
+ case DOMAIN_ADMIN:
+ case RESOURCE_DOMAIN_ADMIN:
+ return "DomainAdmin";
+ default:
+ return "User";
+ }
+ }
+
+ /**
+ * Remove an account's deployments (SPEC.md section 9).
+ *
+ * Only the ownership rows: the engine owns the running workloads and
+ * removes them when it next reconciles, because the spec they were
+ * deployed from no longer lists them. Deleting here and there would
+ * race.
+ *
+ * NOTE: CloudStack 4.23 exposes no plugin-facing account-cleanup
+ * interface — AccountCleanupTask is internal to AccountManagerImpl —
+ * so this is not yet wired to account deletion. See PROGRESS.md.
+ */
+ @Override
+ public int cleanupAccount(long accountId) {
+ if (deploymentDao == null) {
+ return 0;
+ }
+ return deploymentDao.removeByAccount(accountId);
+ }
+
+ /**
+ * Run a command's work so CloudStack records how it ended.
+ *
+ *
Two things have to be true for an event to appear, and both
+ * were learned from a server that recorded none.
+ *
+ *
First, this method has to be on a bean. The advisor in
+ * {@code spring-core-system-context-inheritable.xml} is
+ * {@code execution(* *(..)) && @annotation(ActionEvent)}, so it
+ * wraps beans and nothing else; a command carrying the same
+ * annotation is never proxied and never intercepted. The manager
+ * is a bean, so a call through the injected {@code AiServicesService}
+ * interface goes through the proxy and the interceptor sees it.
+ *
+ *
Second, the event type has to reach the interceptor through
+ * the {@link CallContext}. {@code interceptComplete} returns early
+ * when the annotation's {@code eventType} is empty, and the
+ * fallback it would otherwise use, {@code ctx.getEventType()}, is
+ * never populated — nothing in CloudStack's API path calls
+ * {@code setEventType}. So the context is stamped here, inside the
+ * proxied call, before the work runs: {@code interceptComplete} and
+ * {@code interceptException} both read it afterwards and record
+ * Completed or Failed against the command's own type.
+ *
+ *
{@code async = false} is deliberate. The interceptor's
+ * {@code interceptStart} publishes a Started event only when the
+ * annotation says async, and for an async command {@code ApiServer}
+ * has already written the Scheduled event before the job began;
+ * asking for a second one would put two openers against one close.
+ */
+ @Override
+ @ActionEvent(eventType = "", eventDescription = "", async = false)
+ public void recordEvent(String eventType, String eventDescription, Runnable work) {
+ CallContext ctx = CallContext.current();
+ if (ctx != null) {
+ ctx.setEventType(eventType);
+ ctx.setEventDescription(eventDescription);
+ }
+ work.run();
+ }
+
+ /**
+ * Which GPU node VMs are running on a host.
+ *
+ *
Asked of CloudStack rather than the engine: CloudStack is the
+ * IaaS authority and already knows what runs where, and the naming
+ * scheme {@code aisvc--} is what identifies ours
+ * (CLAUDE.md). The engine would have to be told the same thing to
+ * answer it, so there is nothing to gain by routing through it.
+ */
+ List gpuNodesOnHost(long hostId) {
+ if (vmInstanceDao == null) {
+ return new ArrayList<>();
+ }
+ List nodes = new ArrayList<>();
+ for (VMInstanceVO vm : vmInstanceDao.listUpByHostId(hostId)) {
+ if (vm.getInstanceName() != null && vm.getInstanceName().startsWith(NODE_NAME_PREFIX)) {
+ nodes.add(vm.getInstanceName());
+ }
+ }
+ return nodes;
+ }
+
+ /**
+ * Start listening for host maintenance, where the install allows it.
+ *
+ *
Returns normally either way: a missing event bus is a
+ * limitation to report, not a reason to refuse to start. See
+ * {@link AiMaintenanceListener} for why this hook and no better one.
+ */
+ @Override
+ public boolean start() {
+ // CloudStack has no way for a plugin JAR to join its schema
+ // upgrade chain, so the one table this plugin owns is created
+ // here. See AiServicesSchema for why, and why a failure is
+ // logged rather than fatal.
+ applySchema();
+
+ maintenanceListener = new AiMaintenanceListener(
+ new MaintenanceDrain(
+ this::gpuNodesOnHost,
+ this::drainNodeForMaintenance,
+ this::alertForcedDrainNeeded,
+ AiServicesConfig.MaintenanceDrainTimeout.value()),
+ this::hostIdForUuid);
+ maintenanceListener.subscribe(resolveEventBus());
+ return true;
+ }
+
+ /**
+ * Create the plugin's table if it is not there.
+ *
+ *
Its own method so startup can be tested without a database,
+ * the same seam {@link #v2Enabled()} uses.
+ */
+ boolean applySchema() {
+ return AiServicesSchema.applyToCloudDb();
+ }
+
+ /**
+ * The configured event bus, or null when there is none.
+ *
+ *
No event bus plugin is enabled in a default CloudStack install,
+ * so its absence is the normal case and not an error. CloudStack's own
+ * code resolves it this way for the same reason.
+ *
+ *
Package-private so startup can be tested without a Spring
+ * context, the same seam {@link #v2Enabled()} and
+ * {@link #applySchema()} use. Note that under {@code -ea}
+ * CloudStack's {@code ComponentContext.getComponent} asserts rather
+ * than throwing one of the exceptions caught here.
+ */
+ EventBus resolveEventBus() {
+ try {
+ return ComponentContext.getComponent(EventBus.class);
+ } catch (NoSuchBeanDefinitionException | IllegalStateException absent) {
+ return null;
+ }
+ }
+
+ private Long hostIdForUuid(String uuid) {
+ if (hostDao == null || uuid == null) {
+ return null;
+ }
+ HostVO host = hostDao.findByUuid(uuid);
+ return host == null ? null : host.getId();
+ }
+
+ private MaintenanceDrain.Outcome drainNodeForMaintenance(
+ String nodeId, CallerContext caller, int timeoutSeconds) {
+ try {
+ EngineResponse accepted = getEngineClient()
+ .post("/v1/nodes/" + nodeId + "/drain", caller, "");
+ if (!accepted.isAccepted()) {
+ return MaintenanceDrain.Outcome.TIMED_OUT;
+ }
+ EngineJob started = EngineJob.parse(accepted.getBody());
+ EngineJobPoller poller = new EngineJobPoller(
+ getEngineClient(), timeoutSeconds * 1000L);
+ EngineJob job = poller.await(started.getJobId(), caller);
+ // A failed drain job is the engine saying there is not enough
+ // capacity elsewhere, which is the operator's call to make.
+ return job.isSuccess()
+ ? MaintenanceDrain.Outcome.DRAINED
+ : MaintenanceDrain.Outcome.NEEDS_FORCE;
+ } catch (EngineException e) {
+ LOG.warn("Draining {} failed before maintenance: {}", nodeId, e.getMessage());
+ return MaintenanceDrain.Outcome.TIMED_OUT;
+ }
+ }
+
+ private void alertForcedDrainNeeded(long hostId, String nodeId, String reason) {
+ // Maintenance has no user session behind it, so this is logged
+ // rather than raised through CallContext, which would be null here.
+ LOG.warn("AI Services: host {} needs a forced drain of {} ({}). Event {}.",
+ hostId, nodeId, reason, AiServicesEvents.NODE_DRAIN);
+ }
+
+ /** Test seam for the DAO, which is otherwise Spring-injected. */
+ void setDeploymentDao(AiDeploymentDao dao) {
+ this.deploymentDao = dao;
+ }
+
+ /** Test seam for the domain DAO. */
+ void setDomainDao(DomainDao dao) {
+ this.domainDao = dao;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesSchema.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesSchema.java
new file mode 100644
index 000000000000..eabebf024ed5
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesSchema.java
@@ -0,0 +1,182 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import com.cloud.utils.db.TransactionLegacy;
+
+/**
+ * Creates the plugin's one table (SPEC.md section 9).
+ *
+ *
Why the plugin does this itself. CloudStack applies schema
+ * through {@code DbUpgrade} classes registered in its core upgrade
+ * chain, and the precedent for a plugin's own tables — Quota — is that
+ * they live in CloudStack's {@code engine/schema} upgrade scripts.
+ * Neither is open to a plugin JAR dropped into an existing management
+ * server, so {@code META-INF/db/schema-ai-services.sql} shipped with
+ * nothing to run it: the table was never created, and the first
+ * {@code deployAiModel} would have failed on a missing table.
+ *
+ *
Applying it at startup is the smaller of two evils. It is safe
+ * because the script is {@code CREATE TABLE IF NOT EXISTS}: a server
+ * that already has the table does nothing. If this plugin is ever
+ * merged upstream, the right home for the table is CloudStack's own
+ * upgrade path and this class should go.
+ *
+ *
The parser is deliberate rather than a split on {@code ';'}: a
+ * semicolon inside a {@code COMMENT} string would otherwise be cut in
+ * half and executed as two broken statements.
+ */
+public final class AiServicesSchema {
+
+ private static final Logger LOG = LogManager.getLogger(AiServicesSchema.class);
+
+ static final String RESOURCE = "META-INF/db/schema-ai-services.sql";
+
+ /** One statement, already stripped of comments. */
+ public interface StatementRunner {
+ void run(String sql) throws SQLException;
+ }
+
+ private AiServicesSchema() {
+ }
+
+ /** The bundled script, or "" if it is not on the classpath. */
+ public static String script() {
+ ClassLoader loader = AiServicesSchema.class.getClassLoader();
+ try (InputStream in = loader.getResourceAsStream(RESOURCE)) {
+ if (in == null) {
+ LOG.error("{} is not on the classpath; ai_deployment cannot be created", RESOURCE);
+ return "";
+ }
+ return new String(in.readAllBytes(), StandardCharsets.UTF_8);
+ } catch (IOException exc) {
+ LOG.error("could not read {}", RESOURCE, exc);
+ return "";
+ }
+ }
+
+ /**
+ * Split a script into executable statements.
+ *
+ *
Drops {@code --} comments and blank lines, and treats a
+ * semicolon inside a single-quoted string as data rather than a
+ * terminator. SQL escapes a quote by doubling it, which is why the
+ * real script's {@code the engine''s identifier} does not end its
+ * string.
+ */
+ public static List statements(String script) {
+ List found = new ArrayList<>();
+ StringBuilder current = new StringBuilder();
+ boolean inString = false;
+
+ for (int i = 0; i < script.length(); i++) {
+ char c = script.charAt(i);
+
+ if (!inString && c == '-' && i + 1 < script.length() && script.charAt(i + 1) == '-') {
+ // A line comment: skip to the newline, which is kept so
+ // the statement either side stays separated.
+ while (i < script.length() && script.charAt(i) != '\n') {
+ i++;
+ }
+ current.append('\n');
+ continue;
+ }
+
+ if (c == '\'') {
+ // A doubled quote is an escaped one, not the end.
+ if (inString && i + 1 < script.length() && script.charAt(i + 1) == '\'') {
+ current.append(c).append(script.charAt(i + 1));
+ i++;
+ continue;
+ }
+ inString = !inString;
+ }
+
+ if (c == ';' && !inString) {
+ add(found, current);
+ current.setLength(0);
+ continue;
+ }
+ current.append(c);
+ }
+ add(found, current);
+ return found;
+ }
+
+ private static void add(List found, CharSequence candidate) {
+ String trimmed = candidate.toString().trim();
+ if (!trimmed.isEmpty()) {
+ found.add(trimmed);
+ }
+ }
+
+ /**
+ * Run every statement in the bundled script.
+ *
+ *
Throws on the first failure rather than carrying on: a
+ * half-created schema that reports success is worse than one that
+ * says what broke.
+ */
+ public static void apply(StatementRunner runner) throws SQLException {
+ for (String statement : statements(script())) {
+ runner.run(statement);
+ }
+ }
+
+ /**
+ * Apply the schema to CloudStack's own database.
+ *
+ *
Returns whether it worked. The caller logs and carries on: a
+ * management server should not fail to start because an optional
+ * plugin could not create its table. Every command that needs the
+ * table will fail loudly instead, and this logs the reason once at
+ * startup where an operator will see it.
+ */
+ public static boolean applyToCloudDb() {
+ TransactionLegacy transaction = TransactionLegacy.open(TransactionLegacy.CLOUD_DB);
+ try {
+ Connection connection = transaction.getConnection();
+ apply(sql -> {
+ try (Statement statement = connection.createStatement()) {
+ statement.execute(sql);
+ }
+ });
+ LOG.info("ai_deployment is present");
+ return true;
+ } catch (SQLException | RuntimeException exc) {
+ LOG.error(
+ "could not create the ai_deployment table from {}. AI Services commands that "
+ + "own a deployment will fail until it exists; apply the script by hand "
+ + "against the cloud database.",
+ RESOURCE,
+ exc);
+ return false;
+ } finally {
+ transaction.close();
+ }
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesService.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesService.java
new file mode 100644
index 000000000000..e7f7aea6abd6
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesService.java
@@ -0,0 +1,68 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.ai.engine.EngineClient;
+
+import com.cloud.utils.component.PluggableService;
+
+/**
+ * The AI Services plugin's front door (SPEC.md section 9).
+ *
+ * Extends {@link PluggableService} so CloudStack registers the commands
+ * this plugin provides and applies role permissions to them.
+ */
+public interface AiServicesService extends PluggableService {
+
+ /** Whether AI Services is enabled in the given zone. */
+ boolean isEnabledInZone(long zoneId);
+
+ /** The engine client, configured from ai.services.engine.*. */
+ EngineClient getEngineClient();
+
+ /** The caller context for the current CloudStack session. */
+ CallerContext currentCaller();
+
+ /**
+ * Remove every AI resource an account owns (SPEC.md section 9).
+ *
+ * @return how many ownership rows were removed.
+ */
+ int cleanupAccount(long accountId);
+
+ /**
+ * Run a command's work so CloudStack records how it ended.
+ *
+ * Every write command calls this instead of doing its work inline,
+ * because `ActionEventInterceptor` is a Spring AOP advisor and so
+ * only sees methods on *beans*. A command is not one — CloudStack
+ * builds it with `ComponentContext.inject`, which autowires the
+ * instance and returns it unproxied — so `@ActionEvent` on a
+ * command's own `execute()` is never consulted, however correctly
+ * it is written. The manager is a bean, which is why CloudStack's
+ * own commands delegate to a manager for exactly this.
+ *
+ * The work is a `Runnable` rather than a value-returning call
+ * because the interceptor only needs to know whether it threw:
+ * returning normally records Completed, throwing records Failed,
+ * and the command keeps its own result through its own fields.
+ *
+ * @param eventType one of {@link AiServicesEvents}.
+ * @param eventDescription what the operator should read.
+ * @param work the command's work; exceptions propagate.
+ */
+ void recordEvent(String eventType, String eventDescription, Runnable work);
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesUsageTypes.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesUsageTypes.java
new file mode 100644
index 000000000000..2b475235bc39
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/AiServicesUsageTypes.java
@@ -0,0 +1,60 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+/**
+ * Usage types for AI Services (SPEC.md section 9).
+ *
+ * "The plugin pulls /v1/usage hourly and writes usage events for existing
+ * billing integrations." These ids sit above CloudStack's own range so a
+ * provider's billing pipeline can tell them apart without ambiguity;
+ * CloudStack's built-in types stop well below 100.
+ */
+public final class AiServicesUsageTypes {
+
+ private AiServicesUsageTypes() {
+ }
+
+ public static final int INPUT_TOKENS = 100;
+ public static final int OUTPUT_TOKENS = 101;
+ public static final int GPU_HOURS = 102;
+ /** v2: the premium charged on top of the base price for a LoRA adapter. */
+ public static final int ADAPTER_PREMIUM = 103;
+ /** v2: batch tokens, billed at a discount to the online rate. */
+ public static final int BATCH_TOKENS = 104;
+
+ public static String describe(int usageType) {
+ switch (usageType) {
+ case INPUT_TOKENS:
+ return "AI input tokens";
+ case OUTPUT_TOKENS:
+ return "AI output tokens";
+ case GPU_HOURS:
+ return "AI GPU hours";
+ case ADAPTER_PREMIUM:
+ return "AI adapter premium";
+ case BATCH_TOKENS:
+ return "AI batch tokens";
+ default:
+ throw new IllegalArgumentException("not an AI Services usage type: " + usageType);
+ }
+ }
+
+ public static int[] all() {
+ return new int[] {
+ INPUT_TOKENS, OUTPUT_TOKENS, GPU_HOURS, ADAPTER_PREMIUM, BATCH_TOKENS,
+ };
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmd.java
new file mode 100644
index 000000000000..ccaccc08001f
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmd.java
@@ -0,0 +1,154 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import javax.inject.Inject;
+
+import org.apache.cloudstack.ai.AiServicesConfig;
+import org.apache.cloudstack.ai.AiServicesService;
+import org.apache.cloudstack.ai.engine.EngineException;
+import org.apache.cloudstack.ai.engine.EnginePaths;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.ai.engine.EngineJobPoller;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.api.ApiErrorCode;
+import org.apache.cloudstack.api.BaseAsyncCmd;
+import org.apache.cloudstack.api.ServerApiException;
+import org.apache.cloudstack.context.CallContext;
+
+/**
+ * Bridges a CloudStack async job onto an engine job (SPEC.md section 9).
+ *
+ * "State-changing commands extend BaseAsyncCmd and run as CloudStack
+ * async jobs that poll the engine's /v1/jobs/{id}." This method body runs
+ * inside the CloudStack job, so blocking here is the point: the API
+ * caller already holds a CloudStack job id to poll, and the two job
+ * states stay in step because the engine uses CloudStack's own values.
+ */
+public abstract class AiServicesAsyncCmd extends BaseAsyncCmd {
+
+ @Inject
+ protected AiServicesService aiServices;
+
+ /** Engine endpoint this command calls, for example /v1/deployments. */
+ protected abstract String enginePath();
+
+ /** The request body, or null for a verb that carries none. */
+ protected String engineBody() {
+ return null;
+ }
+
+ /** HTTP verb; POST unless a command says otherwise. */
+ protected String engineMethod() {
+ return "POST";
+ }
+
+ /** Turn the finished engine job into this command's response. */
+ protected abstract void onSuccess(EngineJob job);
+
+ @Override
+ public void execute() throws ServerApiException {
+ // Through the manager, because that is the only object Spring
+ // proxies — see AiServicesService.recordEvent. ApiServer has
+ // already written this command's Scheduled event; what the
+ // recorder adds is the Completed or Failed that closes it, and
+ // the whole poll has to sit inside the call for a job that
+ // fails after being accepted to be recorded as Failed.
+ aiServices.recordEvent(getEventType(), getEventDescription(), () -> {
+ EngineJob job = runAndAwait();
+ onSuccess(job);
+ });
+ }
+
+ /**
+ * Start the engine job and wait for it.
+ *
+ * A 202 is the contract; anything else means the engine did not
+ * accept the command, and treating a 200 as success would skip the
+ * job entirely and report work that never happened.
+ */
+ protected EngineJob runAndAwait() throws ServerApiException {
+ try {
+ EngineResponse accepted = send();
+ if (!accepted.isAccepted()) {
+ throw new ServerApiException(ApiErrorCode.INTERNAL_ERROR,
+ "the AI Services engine did not accept " + getEventType()
+ + ": HTTP " + accepted.getStatusCode()
+ + accepted.explain());
+ }
+
+ EngineJob started = EngineJob.parse(accepted.getBody());
+ EngineJobPoller poller = new EngineJobPoller(
+ aiServices.getEngineClient(), timeoutMillis());
+ return poller.await(started.getJobId(), aiServices.currentCaller());
+ } catch (EngineException failure) {
+ throw new ServerApiException(errorCodeFor(failure), failure.getMessage());
+ }
+ }
+
+ private EngineResponse send() {
+ String path = enginePath();
+ switch (engineMethod()) {
+ case "DELETE":
+ return aiServices.getEngineClient().delete(path, aiServices.currentCaller());
+ case "PATCH":
+ return aiServices.getEngineClient()
+ .patch(path, aiServices.currentCaller(), engineBody());
+ default:
+ return aiServices.getEngineClient()
+ .post(path, aiServices.currentCaller(), engineBody());
+ }
+ }
+
+ /**
+ * Map an engine failure onto a CloudStack error code.
+ *
+ * A 403 from the engine is a permission decision and must not reach
+ * the tenant as an internal error, which would hide why it failed.
+ */
+ static ApiErrorCode errorCodeFor(EngineException failure) {
+ switch (failure.getStatusCode()) {
+ case 400:
+ case 422:
+ return ApiErrorCode.PARAM_ERROR;
+ case 403:
+ return ApiErrorCode.ACCOUNT_ERROR;
+ case 404:
+ return ApiErrorCode.PARAM_ERROR;
+ case 503:
+ return ApiErrorCode.RESOURCE_UNAVAILABLE_ERROR;
+ default:
+ return ApiErrorCode.INTERNAL_ERROR;
+ }
+ }
+
+ private long timeoutMillis() {
+ Integer seconds = AiServicesConfig.EngineTimeout.value();
+ // The engine's own job may take far longer than one HTTP call;
+ // mirroring a 70B model is minutes, so the poll budget is
+ // separate from the per-request timeout.
+ return (seconds == null ? 30L : seconds) * 60L * 1000L;
+ }
+
+ /** Append a query parameter to an engine path. */
+ protected static String withQuery(String path, String name, Object value) {
+ return EnginePaths.withQuery(path, name, value);
+ }
+
+ @Override
+ public long getEntityOwnerId() {
+ return CallContext.current().getCallingAccount().getId();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesListCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesListCmd.java
new file mode 100644
index 000000000000..5b5509da67e5
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesListCmd.java
@@ -0,0 +1,106 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.cloudstack.api.ApiConstants;
+import org.apache.cloudstack.api.BaseResponse;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.BaseCmd.CommandType;
+import org.apache.cloudstack.api.response.ListResponse;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+
+/**
+ * A command that lists what the engine returns (SPEC.md section 9).
+ *
+ * The engine has already filtered the collection by caller context, so
+ * the count here is the caller's count — which is what makes "two
+ * tenants cannot see each other's endpoints" (section 14) a property of
+ * one place rather than of every list command.
+ */
+public abstract class AiServicesListCmd extends AiServicesSyncCmd {
+
+ /**
+ * The row CloudStack is opening a detail view for.
+ *
+ * AutogenView renders a detail page by calling the same list command
+ * with `id=`. A command that does not declare the
+ * parameter has it dropped in silence, so the engine answers with
+ * everything and the view draws the first row — which is what every
+ * detail page in this section used to do, whatever had been clicked.
+ */
+ @Parameter(name = ApiConstants.ID, type = CommandType.STRING,
+ description = "the record to show, when opening one from a list")
+ private String id;
+
+ /** The JSON array field holding the items, for example "models". */
+ protected abstract String itemsKey();
+
+ /**
+ * Whether this command's screen opens a detail view at all. A list with
+ * no detail page is never called with an `id`, and filtering one that is
+ * would silently empty it.
+ */
+ protected boolean filtersById() {
+ return false;
+ }
+
+ /**
+ * The engine field an `id` is matched against. A row's key is
+ * `record.id || record.name`, so this is "id" wherever the response
+ * carries one, and the field the screen builds its name from otherwise.
+ */
+ protected String identityField() {
+ return "id";
+ }
+
+ /** Whether this engine object is the one that was asked for. */
+ private boolean wanted(JsonObject item) {
+ if (!filtersById() || id == null || id.isEmpty()) {
+ return true;
+ }
+ JsonElement value = item.get(identityField());
+ if (value == null || value.isJsonNull() || !value.isJsonPrimitive()) {
+ return false;
+ }
+ return id.equals(value.getAsString());
+ }
+
+ /** Map one engine object onto a CloudStack response. */
+ protected abstract T mapItem(JsonObject item);
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ List items = new ArrayList<>();
+ if (body.has(itemsKey()) && body.get(itemsKey()).isJsonArray()) {
+ JsonArray entries = body.getAsJsonArray(itemsKey());
+ for (JsonElement element : entries) {
+ if (element.isJsonObject() && wanted(element.getAsJsonObject())) {
+ items.add(mapItem(element.getAsJsonObject()));
+ }
+ }
+ }
+
+ ListResponse response = new ListResponse<>();
+ response.setResponses(items, items.size());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmd.java
new file mode 100644
index 000000000000..af1df4b3f404
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmd.java
@@ -0,0 +1,147 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import javax.inject.Inject;
+
+import org.apache.cloudstack.ai.AiServicesService;
+import org.apache.cloudstack.ai.engine.EngineException;
+import org.apache.cloudstack.ai.engine.EnginePaths;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.api.BaseCmd;
+import org.apache.cloudstack.api.ServerApiException;
+import org.apache.cloudstack.context.CallContext;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/**
+ * A command that calls the engine and answers immediately
+ * (SPEC.md section 9).
+ *
+ * Every response is already filtered by the engine against the caller
+ * context, so these commands pass identity through rather than deciding
+ * visibility themselves — one place to get it right instead of thirty.
+ */
+public abstract class AiServicesSyncCmd extends BaseCmd {
+
+ @Inject
+ protected AiServicesService aiServices;
+
+ protected abstract String enginePath();
+
+ protected String engineMethod() {
+ return "GET";
+ }
+
+ protected String engineBody() {
+ return null;
+ }
+
+ /** Build this command's response from the engine's answer. */
+ protected abstract void onSuccess(JsonObject body);
+
+ /**
+ * The event this command records, or null if it records none.
+ *
+ * A read is not an event, and a list command inherits this null —
+ * which is the whole gate: {@link #execute()} records nothing
+ * unless a command names a type here. The generator emits an
+ * override for every write that declares one in the command map.
+ */
+ public String getEventType() {
+ return null;
+ }
+
+ /** What an operator should read in the event log. */
+ public String getEventDescription() {
+ return null;
+ }
+
+ @Override
+ public void execute() throws ServerApiException {
+ String eventType = getEventType();
+ if (eventType == null) {
+ doExecute();
+ return;
+ }
+ // Through the manager, because that is the only object Spring
+ // proxies — see AiServicesService.recordEvent. The work has to
+ // happen *inside* this call for a failure to be recorded as
+ // Failed rather than leaving the command's event unfinished.
+ aiServices.recordEvent(eventType, getEventDescription(), this::doExecute);
+ }
+
+ private void doExecute() {
+ JsonObject body = callEngine();
+ onSuccess(body);
+ }
+
+ protected JsonObject callEngine() throws ServerApiException {
+ try {
+ EngineResponse answer = send();
+ if (!answer.isSuccess()) {
+ throw new ServerApiException(
+ AiServicesAsyncCmd.errorCodeFor(
+ new EngineException("", answer.getStatusCode(), null)),
+ "the AI Services engine returned " + answer.getStatusCode()
+ + " for " + enginePath() + answer.explain());
+ }
+ return parse(answer.getBody());
+ } catch (EngineException failure) {
+ throw new ServerApiException(
+ AiServicesAsyncCmd.errorCodeFor(failure), failure.getMessage());
+ }
+ }
+
+ private EngineResponse send() {
+ String path = enginePath();
+ switch (engineMethod()) {
+ case "POST":
+ return aiServices.getEngineClient()
+ .post(path, aiServices.currentCaller(), engineBody());
+ case "PATCH":
+ return aiServices.getEngineClient()
+ .patch(path, aiServices.currentCaller(), engineBody());
+ case "DELETE":
+ return aiServices.getEngineClient().delete(path, aiServices.currentCaller());
+ default:
+ return aiServices.getEngineClient().get(path, aiServices.currentCaller());
+ }
+ }
+
+ static JsonObject parse(String body) {
+ if (body == null || body.trim().isEmpty()) {
+ return new JsonObject();
+ }
+ try {
+ return JsonParser.parseString(body).getAsJsonObject();
+ } catch (RuntimeException malformed) {
+ throw new EngineException(
+ "the AI Services engine returned an unreadable body: "
+ + malformed.getMessage());
+ }
+ }
+
+ /** Append a query parameter to an engine path. */
+ protected static String withQuery(String path, String name, Object value) {
+ return EnginePaths.withQuery(path, name, value);
+ }
+
+ @Override
+ public long getEntityOwnerId() {
+ return CallContext.current().getCallingAccount().getId();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ApproveAiModelCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ApproveAiModelCmd.java
new file mode 100644
index 000000000000..af2c37c17b47
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ApproveAiModelCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Approves a mirror request. (SPEC.md section 9). */
+@APICommand(name = ApproveAiModelCmd.APINAME,
+ description = "Approves a mirror request.",
+ responseObject = AiModelResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ApproveAiModelCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "approveAiModel";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the model to approve")
+ private String modelId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models/" + modelId + "/approve";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiModelResponse response = AiModelResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_PUBLISH;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "approving model " + modelId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AssignAiTuningProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AssignAiTuningProfileCmd.java
new file mode 100644
index 000000000000..0f8b3528cb7f
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/AssignAiTuningProfileCmd.java
@@ -0,0 +1,89 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Assigns a tuning profile at a scope. (SPEC.md section 9). */
+@APICommand(name = AssignAiTuningProfileCmd.APINAME,
+ description = "Assigns a tuning profile at a scope.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class AssignAiTuningProfileCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "assignAiTuningProfile";
+
+ @Parameter(name = "scope", type = CommandType.STRING, required = true,
+ description = "domain, account, deployment or key")
+ private String scope;
+
+ @Parameter(name = "target", type = CommandType.STRING, required = true,
+ description = "what to assign it to")
+ private String target;
+
+ @Parameter(name = "profile", type = CommandType.STRING, required = true,
+ description = "the profile to assign")
+ private String profile;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/assignments";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (scope != null) {
+ body.addProperty("scope", scope);
+ }
+ if (target != null) {
+ body.addProperty("target", target);
+ }
+ if (profile != null) {
+ body.addProperty("profile", profile);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiProfileResponse response = AiProfileResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "assigning tuning profile " + scope;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CancelAiBatchCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CancelAiBatchCmd.java
new file mode 100644
index 000000000000..55190fee4366
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CancelAiBatchCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiBatchResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Cancels a batch job. (SPEC.md section 9). */
+@APICommand(name = CancelAiBatchCmd.APINAME,
+ description = "Cancels a batch job.",
+ responseObject = AiBatchResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CancelAiBatchCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "cancelAiBatch";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the batch to cancel")
+ private String batchId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/batches/" + batchId + "/cancel";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiBatchResponse response = AiBatchResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.BATCH_CANCEL;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "cancelling batch " + batchId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CheckAiHfModelCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CheckAiHfModelCmd.java
new file mode 100644
index 000000000000..3f7a59182924
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CheckAiHfModelCmd.java
@@ -0,0 +1,60 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiHfCheckResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Reports whether a Hugging Face model can be served. (SPEC.md section 9). */
+@APICommand(name = CheckAiHfModelCmd.APINAME,
+ description = "Reports whether a Hugging Face model can be served.",
+ responseObject = AiHfCheckResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class CheckAiHfModelCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "checkAiHfModel";
+
+ @Parameter(name = "repoid", type = CommandType.STRING, required = true,
+ description = "the repository to check")
+ private String repoId;
+
+ @Parameter(name = "revision", type = CommandType.STRING, required = true,
+ description = "the commit to check")
+ private String revision;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/hf/check";
+ path = withQuery(path, "repo_id", repoId);
+ path = withQuery(path, "revision", revision);
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiHfCheckResponse response = AiHfCheckResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiApiKeyCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiApiKeyCmd.java
new file mode 100644
index 000000000000..090389c021dd
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiApiKeyCmd.java
@@ -0,0 +1,122 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiApiKeyResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+
+/** Creates a scoped API key. The secret is shown once. (SPEC.md section 9). */
+@APICommand(name = CreateAiApiKeyCmd.APINAME,
+ description = "Creates a scoped API key. The secret is shown once.",
+ responseObject = AiApiKeyResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = true,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiApiKeyCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "createAiApiKey";
+
+ @Parameter(name = "name", type = CommandType.STRING, required = true,
+ description = "a name for the key")
+ private String name;
+
+ @Parameter(name = "models", type = CommandType.STRING,
+ description = "models this key may use; all if unset")
+ private String models;
+
+ @Parameter(name = "cidrlist", type = CommandType.STRING,
+ description = "CIDRs the key may be used from")
+ private String cidrList;
+
+ @Parameter(name = "expires", type = CommandType.STRING,
+ description = "when the key should expire")
+ private String expires;
+
+ @Parameter(name = "ratelimitrpm", type = CommandType.INTEGER,
+ description = "requests per minute this key may make")
+ private Integer rateLimitRpm;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/keys";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (name != null) {
+ body.addProperty("name", name);
+ }
+ if (models != null) {
+ JsonArray valuesModels = new JsonArray();
+ for (String part : models.split(",")) {
+ String trimmed = part.trim();
+ if (!trimmed.isEmpty()) {
+ valuesModels.add(trimmed);
+ }
+ }
+ body.add("allowed_models", valuesModels);
+ }
+ if (cidrList != null) {
+ JsonArray valuesCidrList = new JsonArray();
+ for (String part : cidrList.split(",")) {
+ String trimmed = part.trim();
+ if (!trimmed.isEmpty()) {
+ valuesCidrList.add(trimmed);
+ }
+ }
+ body.add("cidrs", valuesCidrList);
+ }
+ if (expires != null) {
+ body.addProperty("expires_at", expires);
+ }
+ if (rateLimitRpm != null) {
+ body.addProperty("rate_limit_rpm", rateLimitRpm);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiApiKeyResponse response = AiApiKeyResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.KEY_CREATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating API key " + name;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBatchCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBatchCmd.java
new file mode 100644
index 000000000000..57221adf5cf9
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBatchCmd.java
@@ -0,0 +1,89 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiBatchResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Submits a batch inference job. (SPEC.md section 9). */
+@APICommand(name = CreateAiBatchCmd.APINAME,
+ description = "Submits a batch inference job.",
+ responseObject = AiBatchResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiBatchCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "createAiBatch";
+
+ @Parameter(name = "model", type = CommandType.STRING, required = true,
+ description = "the model to run against")
+ private String model;
+
+ @Parameter(name = "input", type = CommandType.STRING, required = true, length = 65535,
+ description = "the batch's JSONL, one request per line")
+ private String input;
+
+ @Parameter(name = "inputuri", type = CommandType.STRING,
+ description = "where the JSONL input is")
+ private String inputUri;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/batches";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (model != null) {
+ body.addProperty("model", model);
+ }
+ if (input != null) {
+ body.addProperty("input", input);
+ }
+ if (inputUri != null) {
+ body.addProperty("input_uri", inputUri);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiBatchResponse response = AiBatchResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.BATCH_CREATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "submitting batch " + model;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBudgetCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBudgetCmd.java
new file mode 100644
index 000000000000..fe17cfcf4407
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiBudgetCmd.java
@@ -0,0 +1,107 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiBudgetResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Creates a monthly budget. (SPEC.md section 9). */
+@APICommand(name = CreateAiBudgetCmd.APINAME,
+ description = "Creates a monthly budget.",
+ responseObject = AiBudgetResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiBudgetCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "createAiBudget";
+
+ @Parameter(name = "account", type = CommandType.STRING, required = true,
+ description = "the account the budget applies to")
+ private String account;
+
+ @Parameter(name = "domain", type = CommandType.STRING, required = true,
+ description = "the domain path that account is in")
+ private String domainPath;
+
+ @Parameter(name = "monthly", type = CommandType.STRING, required = true,
+ description = "the monthly limit")
+ private String monthly;
+
+ @Parameter(name = "currency", type = CommandType.STRING,
+ description = "the currency")
+ private String currency;
+
+ @Parameter(name = "onexceed", type = CommandType.STRING,
+ description = "alert or block at 100%")
+ private String onExceed;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/budgets";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (account != null) {
+ body.addProperty("account", account);
+ }
+ if (domainPath != null) {
+ body.addProperty("domain", domainPath);
+ }
+ if (monthly != null) {
+ body.addProperty("monthly", monthly);
+ }
+ if (currency != null) {
+ body.addProperty("currency", currency);
+ }
+ if (onExceed != null) {
+ body.addProperty("on_exceed", onExceed);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiBudgetResponse response = AiBudgetResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.BUDGET_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating budget for " + account;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGenerationProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGenerationProfileCmd.java
new file mode 100644
index 000000000000..d71d008eb996
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGenerationProfileCmd.java
@@ -0,0 +1,86 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Creates a generation profile. (SPEC.md section 9). */
+@APICommand(name = CreateAiGenerationProfileCmd.APINAME,
+ description = "Creates a generation profile.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiGenerationProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "createAiGenerationProfile";
+
+ @Parameter(name = "name", type = CommandType.STRING, required = true,
+ description = "the profile name")
+ private String name;
+
+ @Parameter(name = "params", type = CommandType.STRING, required = true,
+ description = "parameters and policies as JSON")
+ private String params;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/generation";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (name != null) {
+ body.addProperty("name", name);
+ }
+ if (params != null) {
+ body.addProperty("params", params);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiProfileResponse response = AiProfileResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating generation profile " + name;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGuardrailProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGuardrailProfileCmd.java
new file mode 100644
index 000000000000..af66151c883d
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiGuardrailProfileCmd.java
@@ -0,0 +1,100 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiGuardrailProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Creates a guardrail profile. (SPEC.md section 9). */
+@APICommand(name = CreateAiGuardrailProfileCmd.APINAME,
+ description = "Creates a guardrail profile.",
+ responseObject = AiGuardrailProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiGuardrailProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "createAiGuardrailProfile";
+
+ @Parameter(name = "name", type = CommandType.STRING, required = true,
+ description = "a name for the profile")
+ private String name;
+
+ @Parameter(name = "scope", type = CommandType.STRING,
+ description = "the level to bind it at")
+ private String scope;
+
+ @Parameter(name = "target", type = CommandType.STRING,
+ description = "the domain, account or deployment")
+ private String target;
+
+ @Parameter(name = "preset", type = CommandType.STRING,
+ description = "a shipped profile to start from")
+ private String preset;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/guardrail";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (name != null) {
+ body.addProperty("name", name);
+ }
+ if (scope != null) {
+ body.addProperty("scope", scope);
+ }
+ if (target != null) {
+ body.addProperty("target", target);
+ }
+ if (preset != null) {
+ body.addProperty("preset", preset);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiGuardrailProfileResponse response = AiGuardrailProfileResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating guardrail profile " + name;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPlaygroundSessionCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPlaygroundSessionCmd.java
new file mode 100644
index 000000000000..605a990a94aa
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPlaygroundSessionCmd.java
@@ -0,0 +1,79 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiPlaygroundSessionResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Mints a short-lived, model-scoped key for the playground. (SPEC.md section 9). */
+@APICommand(name = CreateAiPlaygroundSessionCmd.APINAME,
+ description = "Mints a short-lived, model-scoped key for the playground.",
+ responseObject = AiPlaygroundSessionResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = true,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiPlaygroundSessionCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "createAiPlaygroundSession";
+
+ @Parameter(name = "model", type = CommandType.STRING, required = true,
+ description = "the model to open a session against")
+ private String model;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/playground/sessions";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (model != null) {
+ body.addProperty("model", model);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiPlaygroundSessionResponse response = AiPlaygroundSessionResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PLAYGROUND_SESSION;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "opening a playground session for " + model;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPrivateEndpointCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPrivateEndpointCmd.java
new file mode 100644
index 000000000000..bab3d2a7919a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiPrivateEndpointCmd.java
@@ -0,0 +1,119 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import com.cloud.exception.InvalidParameterValueException;
+import com.cloud.network.Network;
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiPrivateEndpointResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.NetworkResponse;
+
+import com.google.gson.JsonObject;
+
+/** Attaches an endpoint to a tenant network. (SPEC.md section 9). */
+@APICommand(name = CreateAiPrivateEndpointCmd.APINAME,
+ description = "Attaches an endpoint to a tenant network.",
+ responseObject = AiPrivateEndpointResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class CreateAiPrivateEndpointCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "createAiPrivateEndpoint";
+
+ @Parameter(name = "deployment", type = CommandType.STRING, required = true,
+ description = "the deployment to front")
+ private String deployment;
+
+ @Parameter(name = "networkid", type = CommandType.UUID,
+ entityType = NetworkResponse.class,
+ description = "the VPC tier to attach to")
+ private Long networkId;
+
+ @Parameter(name = "publicenabled", type = CommandType.BOOLEAN,
+ description = "whether the public endpoint stays on")
+ private Boolean publicEnabled;
+
+ @Parameter(name = "customdomain", type = CommandType.STRING,
+ description = "a custom domain")
+ private String customDomain;
+
+ @Parameter(name = "tls", type = CommandType.STRING,
+ description = "where its certificate comes from: none, acme or uploaded")
+ private String tls;
+
+ @Parameter(name = "certificateid", type = CommandType.STRING,
+ description = "an uploaded certificate for it")
+ private String certificateId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/endpoints/private";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (deployment != null) {
+ body.addProperty("deployment", deployment);
+ }
+ if (networkId != null) {
+ Network resolvedNetwork = _entityMgr.findById(Network.class, networkId);
+ if (resolvedNetwork == null) {
+ throw new InvalidParameterValueException(
+ "Unable to find a network with the given id");
+ }
+ body.addProperty("network_id", resolvedNetwork.getUuid());
+ }
+ if (publicEnabled != null) {
+ body.addProperty("public_enabled", publicEnabled);
+ }
+ if (customDomain != null) {
+ body.addProperty("custom_domain", customDomain);
+ }
+ if (tls != null) {
+ body.addProperty("tls", tls);
+ }
+ if (certificateId != null) {
+ body.addProperty("certificate_id", certificateId);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiPrivateEndpointResponse response = AiPrivateEndpointResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "attaching private endpoint " + deployment;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiServingProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiServingProfileCmd.java
new file mode 100644
index 000000000000..a3baa9f14db0
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/CreateAiServingProfileCmd.java
@@ -0,0 +1,82 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Creates a serving profile. (SPEC.md section 9). */
+@APICommand(name = CreateAiServingProfileCmd.APINAME,
+ description = "Creates a serving profile.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class CreateAiServingProfileCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "createAiServingProfile";
+
+ @Parameter(name = "name", type = CommandType.STRING, required = true,
+ description = "the profile name")
+ private String name;
+
+ @Parameter(name = "params", type = CommandType.STRING, required = true,
+ description = "engine parameters as JSON")
+ private String params;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/serving";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (name != null) {
+ body.addProperty("name", name);
+ }
+ if (params != null) {
+ body.addProperty("params", params);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiProfileResponse response = AiProfileResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating serving profile " + name;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiAdapterCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiAdapterCmd.java
new file mode 100644
index 000000000000..2af7559be32a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiAdapterCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Deletes a LoRA adapter. (SPEC.md section 9). */
+@APICommand(name = DeleteAiAdapterCmd.APINAME,
+ description = "Deletes a LoRA adapter.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiAdapterCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "deleteAiAdapter";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the adapter to delete")
+ private String adapterId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/adapters/" + adapterId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.ADAPTER_DELETE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting adapter " + adapterId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiBudgetCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiBudgetCmd.java
new file mode 100644
index 000000000000..63848d0d29d5
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiBudgetCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Deletes a budget. (SPEC.md section 9). */
+@APICommand(name = DeleteAiBudgetCmd.APINAME,
+ description = "Deletes a budget.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiBudgetCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "deleteAiBudget";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the budget to delete")
+ private String budgetId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/budgets/" + budgetId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.BUDGET_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting budget for " + budgetId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiCertificateCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiCertificateCmd.java
new file mode 100644
index 000000000000..76413c51bb54
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiCertificateCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Deletes a certificate. (SPEC.md section 9). */
+@APICommand(name = DeleteAiCertificateCmd.APINAME,
+ description = "Deletes a certificate.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiCertificateCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "deleteAiCertificate";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the certificate to delete")
+ private String certificateId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/certificates/" + certificateId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.CERTIFICATE_DELETE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting certificate for " + certificateId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGenerationProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGenerationProfileCmd.java
new file mode 100644
index 000000000000..28063a52a04f
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGenerationProfileCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Deletes a generation profile. (SPEC.md section 9). */
+@APICommand(name = DeleteAiGenerationProfileCmd.APINAME,
+ description = "Deletes a generation profile.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiGenerationProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "deleteAiGenerationProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to delete")
+ private String profileId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/generation/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting generation profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGuardrailProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGuardrailProfileCmd.java
new file mode 100644
index 000000000000..d079efe1b69b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiGuardrailProfileCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Deletes a guardrail profile. (SPEC.md section 9). */
+@APICommand(name = DeleteAiGuardrailProfileCmd.APINAME,
+ description = "Deletes a guardrail profile.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiGuardrailProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "deleteAiGuardrailProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to delete")
+ private String profileId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/guardrail/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting guardrail profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiModelDeploymentCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiModelDeploymentCmd.java
new file mode 100644
index 000000000000..377748e4a39d
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiModelDeploymentCmd.java
@@ -0,0 +1,73 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.ApiConstants;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+/** deleteAiModelDeployment (SPEC.md section 9). */
+@APICommand(name = DeleteAiModelDeploymentCmd.APINAME,
+ description = "Deletes an AI model deployment.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ // Hand-written, so this list is not generated: the drift
+ // test in tests/unit/test_commands.py holds it to
+ // aisvc/api/commands.py like every other command's.
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiModelDeploymentCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "deleteAiModelDeployment";
+
+ @Parameter(name = ApiConstants.ID, type = CommandType.STRING, required = true,
+ description = "the deployment to delete")
+ private String deploymentId;
+
+ @Override
+ protected String enginePath() {
+ return "/v1/deployments/" + deploymentId;
+ }
+
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_DELETE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting AI model deployment " + deploymentId;
+ }
+
+ public String getDeploymentId() {
+ return deploymentId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiPrivateEndpointCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiPrivateEndpointCmd.java
new file mode 100644
index 000000000000..4a49fe5f1fbb
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiPrivateEndpointCmd.java
@@ -0,0 +1,69 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiPrivateEndpointResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Removes a private endpoint. (SPEC.md section 9). */
+@APICommand(name = DeleteAiPrivateEndpointCmd.APINAME,
+ description = "Removes a private endpoint.",
+ responseObject = AiPrivateEndpointResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeleteAiPrivateEndpointCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "deleteAiPrivateEndpoint";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the exposure to remove")
+ private String exposureId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/endpoints/private/" + exposureId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiPrivateEndpointResponse response = AiPrivateEndpointResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "removing private endpoint " + exposureId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiServingProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiServingProfileCmd.java
new file mode 100644
index 000000000000..670ffa3974e8
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeleteAiServingProfileCmd.java
@@ -0,0 +1,69 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Deletes a serving profile. (SPEC.md section 9). */
+@APICommand(name = DeleteAiServingProfileCmd.APINAME,
+ description = "Deletes a serving profile.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class DeleteAiServingProfileCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "deleteAiServingProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to delete")
+ private String profileId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/serving/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiProfileResponse response = AiProfileResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deleting serving profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeployAiModelCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeployAiModelCmd.java
new file mode 100644
index 000000000000..3634ef30b6d8
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DeployAiModelCmd.java
@@ -0,0 +1,113 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.ApiConstants;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.ZoneResponse;
+
+import com.cloud.dc.DataCenter;
+import com.cloud.exception.InvalidParameterValueException;
+import com.google.gson.JsonObject;
+
+/** deployAiModel (SPEC.md section 9). Async: the engine provisions and serves. */
+@APICommand(name = DeployAiModelCmd.APINAME,
+ description = "Deploys an AI model, returning a job to poll.",
+ responseObject = AiDeploymentResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ // Hand-written, so this list is not generated: the drift
+ // test in tests/unit/test_commands.py holds it to
+ // aisvc/api/commands.py like every other command's.
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class DeployAiModelCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "deployAiModel";
+
+ @Parameter(name = ApiConstants.NAME, type = CommandType.STRING, required = true,
+ description = "the catalog name of the model to deploy")
+ private String modelName;
+
+ @Parameter(name = ApiConstants.ZONE_ID, type = CommandType.UUID,
+ entityType = ZoneResponse.class, required = true,
+ description = "the zone to deploy into")
+ private Long zoneId;
+
+ @Parameter(name = "replicas", type = CommandType.INTEGER,
+ description = "the number of replicas to run; the model's minimum if unset")
+ private Integer replicas;
+
+ @Override
+ protected String enginePath() {
+ return "/v1/deployments";
+ }
+
+ @Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ body.addProperty("model", modelName);
+ // A CommandType.UUID parameter is handed back as CloudStack's
+ // internal numeric id, so sending it raw gives the engine a
+ // number that matches nothing — the same defect the generator
+ // avoids with `resolve=` (CLAUDE.md). The engine knows zones by
+ // the name `platform.yaml` records in `cloudstack_zone`.
+ // Guarded like every generated resolve: the parameter is
+ // required at the API layer, so a null here means a command
+ // built outside dispatch, and the engine reads an absent zone
+ // as "the model's own".
+ if (zoneId != null) {
+ DataCenter resolvedZone = _entityMgr.findById(DataCenter.class, zoneId);
+ if (resolvedZone == null) {
+ throw new InvalidParameterValueException(
+ "Unable to find a zone with the given id");
+ }
+ body.addProperty("zone_id", resolvedZone.getName());
+ }
+ if (replicas != null) {
+ body.addProperty("replicas", replicas);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiDeploymentResponse response = AiDeploymentResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_DEPLOY;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deploying AI model " + modelName;
+ }
+
+ public String getModelName() {
+ return modelName;
+ }
+
+ public Long getZoneId() {
+ return zoneId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DiscoverAiGpuClassesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DiscoverAiGpuClassesCmd.java
new file mode 100644
index 000000000000..59c4f472ca3a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DiscoverAiGpuClassesCmd.java
@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiGpuClassProposalResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Proposes GPU classes from the tags on healthy hosts. (SPEC.md section 9). */
+@APICommand(name = DiscoverAiGpuClassesCmd.APINAME,
+ description = "Proposes GPU classes from the tags on healthy hosts.",
+ responseObject = AiGpuClassProposalResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class DiscoverAiGpuClassesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "discoverAiGpuClasses";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/setup/gpu-discovery";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "classes";
+ }
+
+ @Override
+ protected AiGpuClassProposalResponse mapItem(JsonObject item) {
+ return AiGpuClassProposalResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DrainAiNodeCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DrainAiNodeCmd.java
new file mode 100644
index 000000000000..b49e701a3ee4
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/DrainAiNodeCmd.java
@@ -0,0 +1,69 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiReconcilerRunResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Drains a GPU node before maintenance. (SPEC.md section 9). */
+@APICommand(name = DrainAiNodeCmd.APINAME,
+ description = "Drains a GPU node before maintenance.",
+ responseObject = AiReconcilerRunResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class DrainAiNodeCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "drainAiNode";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the node to drain")
+ private String nodeId;
+
+ @Parameter(name = "force", type = CommandType.BOOLEAN,
+ description = "drain even with no room for the replicas elsewhere")
+ private Boolean force;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/nodes/" + nodeId + "/drain";
+ path = withQuery(path, "force", force);
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiReconcilerRunResponse response = AiReconcilerRunResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.NODE_DRAIN;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "draining GPU node " + nodeId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiBatchResultsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiBatchResultsCmd.java
new file mode 100644
index 000000000000..6c875b82e34e
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiBatchResultsCmd.java
@@ -0,0 +1,54 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiBatchResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Downloads a batch job's results. (SPEC.md section 9). */
+@APICommand(name = GetAiBatchResultsCmd.APINAME,
+ description = "Downloads a batch job's results.",
+ responseObject = AiBatchResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class GetAiBatchResultsCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "getAiBatchResults";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the batch to read")
+ private String batchId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/batches/" + batchId + "/results";
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiBatchResponse response = AiBatchResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiEffectiveParametersCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiEffectiveParametersCmd.java
new file mode 100644
index 000000000000..17fe9bdbf750
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/GetAiEffectiveParametersCmd.java
@@ -0,0 +1,58 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiEffectiveParameterResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Reports every resolved parameter and the level that set it. (SPEC.md section 9). */
+@APICommand(name = GetAiEffectiveParametersCmd.APINAME,
+ description = "Reports every resolved parameter and the level that set it.",
+ responseObject = AiEffectiveParameterResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class GetAiEffectiveParametersCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "getAiEffectiveParameters";
+
+ @Parameter(name = "model", type = CommandType.STRING, required = true,
+ description = "the deployment to resolve for")
+ private String model;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/effective";
+ path = withQuery(path, "model", model);
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "parameters";
+ }
+
+ @Override
+ protected AiEffectiveParameterResponse mapItem(JsonObject item) {
+ return AiEffectiveParameterResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiAdaptersCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiAdaptersCmd.java
new file mode 100644
index 000000000000..c6ba1392ced9
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiAdaptersCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiAdapterResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists the LoRA adapters this account may use. (SPEC.md section 9). */
+@APICommand(name = ListAiAdaptersCmd.APINAME,
+ description = "Lists the LoRA adapters this account may use.",
+ responseObject = AiAdapterResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiAdaptersCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiAdapters";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/adapters";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "adapters";
+ }
+
+ @Override
+ protected AiAdapterResponse mapItem(JsonObject item) {
+ return AiAdapterResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiApiKeysCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiApiKeysCmd.java
new file mode 100644
index 000000000000..a061e6bf17c2
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiApiKeysCmd.java
@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiApiKeyResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists the caller's scoped API keys. (SPEC.md section 9). */
+@APICommand(name = ListAiApiKeysCmd.APINAME,
+ description = "Lists the caller's scoped API keys.",
+ responseObject = AiApiKeyResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiApiKeysCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiApiKeys";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/keys";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "keys";
+ }
+
+ @Override
+ protected AiApiKeyResponse mapItem(JsonObject item) {
+ return AiApiKeyResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBatchesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBatchesCmd.java
new file mode 100644
index 000000000000..557e175f642a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBatchesCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiBatchResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists batch jobs. (SPEC.md section 9). */
+@APICommand(name = ListAiBatchesCmd.APINAME,
+ description = "Lists batch jobs.",
+ responseObject = AiBatchResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiBatchesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiBatches";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/batches";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "batches";
+ }
+
+ @Override
+ protected AiBatchResponse mapItem(JsonObject item) {
+ return AiBatchResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBudgetsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBudgetsCmd.java
new file mode 100644
index 000000000000..e21a0ae1ec47
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiBudgetsCmd.java
@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiBudgetResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists budgets. (SPEC.md section 9). */
+@APICommand(name = ListAiBudgetsCmd.APINAME,
+ description = "Lists budgets.",
+ responseObject = AiBudgetResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiBudgetsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiBudgets";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/budgets";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "budgets";
+ }
+
+ @Override
+ protected AiBudgetResponse mapItem(JsonObject item) {
+ return AiBudgetResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiCertificatesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiCertificatesCmd.java
new file mode 100644
index 000000000000..98bf7e5aceba
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiCertificatesCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiCertificateResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists uploaded certificates. (SPEC.md section 9). */
+@APICommand(name = ListAiCertificatesCmd.APINAME,
+ description = "Lists uploaded certificates.",
+ responseObject = AiCertificateResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiCertificatesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiCertificates";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/certificates";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "certificates";
+ }
+
+ @Override
+ protected AiCertificateResponse mapItem(JsonObject item) {
+ return AiCertificateResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEndpointsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEndpointsCmd.java
new file mode 100644
index 000000000000..df46e64dcf22
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEndpointsCmd.java
@@ -0,0 +1,62 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiEndpointResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists the endpoints the caller may use. (SPEC.md section 9). */
+@APICommand(name = ListAiEndpointsCmd.APINAME,
+ description = "Lists the endpoints the caller may use.",
+ responseObject = AiEndpointResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiEndpointsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiEndpoints";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/endpoints";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "endpoints";
+ }
+
+ @Override
+ protected AiEndpointResponse mapItem(JsonObject item) {
+ return AiEndpointResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+
+ @Override
+ protected String identityField() {
+ return "model";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEvaluationsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEvaluationsCmd.java
new file mode 100644
index 000000000000..3af45799b909
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiEvaluationsCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiEvaluationResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Lists a model's evaluations. (SPEC.md section 9). */
+@APICommand(name = ListAiEvaluationsCmd.APINAME,
+ description = "Lists a model's evaluations.",
+ responseObject = AiEvaluationResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ListAiEvaluationsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiEvaluations";
+
+ @Parameter(name = "model", type = CommandType.STRING, required = true,
+ description = "the model to list")
+ private String modelName;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models/" + modelName + "/evaluations";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "evaluations";
+ }
+
+ @Override
+ protected AiEvaluationResponse mapItem(JsonObject item) {
+ return AiEvaluationResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGenerationProfilesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGenerationProfilesCmd.java
new file mode 100644
index 000000000000..4f0f0734b831
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGenerationProfilesCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists generation profiles. (SPEC.md section 9). */
+@APICommand(name = ListAiGenerationProfilesCmd.APINAME,
+ description = "Lists generation profiles.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiGenerationProfilesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiGenerationProfiles";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/generation";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "profiles";
+ }
+
+ @Override
+ protected AiProfileResponse mapItem(JsonObject item) {
+ return AiProfileResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGpuCapacityCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGpuCapacityCmd.java
new file mode 100644
index 000000000000..0e3276f76a1a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGpuCapacityCmd.java
@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiGpuCapacityResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists GPU capacity per zone and class. (SPEC.md section 9). */
+@APICommand(name = ListAiGpuCapacityCmd.APINAME,
+ description = "Lists GPU capacity per zone and class.",
+ responseObject = AiGpuCapacityResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ListAiGpuCapacityCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiGpuCapacity";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/capacity";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "classes";
+ }
+
+ @Override
+ protected AiGpuCapacityResponse mapItem(JsonObject item) {
+ return AiGpuCapacityResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGuardrailProfilesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGuardrailProfilesCmd.java
new file mode 100644
index 000000000000..851cc185e4fc
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiGuardrailProfilesCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiGuardrailProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists guardrail profiles. (SPEC.md section 9). */
+@APICommand(name = ListAiGuardrailProfilesCmd.APINAME,
+ description = "Lists guardrail profiles.",
+ responseObject = AiGuardrailProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiGuardrailProfilesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiGuardrailProfiles";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/guardrail";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "profiles";
+ }
+
+ @Override
+ protected AiGuardrailProfileResponse mapItem(JsonObject item) {
+ return AiGuardrailProfileResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelDeploymentsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelDeploymentsCmd.java
new file mode 100644
index 000000000000..ec2b3da40424
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelDeploymentsCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists AI model deployments. (SPEC.md section 9). */
+@APICommand(name = ListAiModelDeploymentsCmd.APINAME,
+ description = "Lists AI model deployments.",
+ responseObject = AiDeploymentResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiModelDeploymentsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiModelDeployments";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/deployments";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "deployments";
+ }
+
+ @Override
+ protected AiDeploymentResponse mapItem(JsonObject item) {
+ return AiDeploymentResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelsCmd.java
new file mode 100644
index 000000000000..a16f538ef702
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiModelsCmd.java
@@ -0,0 +1,62 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists AI models published to the caller. (SPEC.md section 9). */
+@APICommand(name = ListAiModelsCmd.APINAME,
+ description = "Lists AI models published to the caller.",
+ responseObject = AiModelResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiModelsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiModels";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "models";
+ }
+
+ @Override
+ protected AiModelResponse mapItem(JsonObject item) {
+ return AiModelResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+
+ @Override
+ protected String identityField() {
+ return "name";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiPrivateEndpointsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiPrivateEndpointsCmd.java
new file mode 100644
index 000000000000..904937f8c812
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiPrivateEndpointsCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiPrivateEndpointResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists private endpoints and how each one is reachable. (SPEC.md section 9). */
+@APICommand(name = ListAiPrivateEndpointsCmd.APINAME,
+ description = "Lists private endpoints and how each one is reachable.",
+ responseObject = AiPrivateEndpointResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiPrivateEndpointsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiPrivateEndpoints";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/endpoints/private";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "endpoints";
+ }
+
+ @Override
+ protected AiPrivateEndpointResponse mapItem(JsonObject item) {
+ return AiPrivateEndpointResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiReconcilerRunsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiReconcilerRunsCmd.java
new file mode 100644
index 000000000000..f0ff544d6221
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiReconcilerRunsCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiReconcilerRunResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists reconciler runs. (SPEC.md section 9). */
+@APICommand(name = ListAiReconcilerRunsCmd.APINAME,
+ description = "Lists reconciler runs.",
+ responseObject = AiReconcilerRunResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ListAiReconcilerRunsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiReconcilerRuns";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/runs";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "runs";
+ }
+
+ @Override
+ protected AiReconcilerRunResponse mapItem(JsonObject item) {
+ return AiReconcilerRunResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiServingProfilesCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiServingProfilesCmd.java
new file mode 100644
index 000000000000..6f372b72a9e6
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiServingProfilesCmd.java
@@ -0,0 +1,57 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Lists serving profiles. (SPEC.md section 9). */
+@APICommand(name = ListAiServingProfilesCmd.APINAME,
+ description = "Lists serving profiles.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ListAiServingProfilesCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiServingProfiles";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/serving";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "profiles";
+ }
+
+ @Override
+ protected AiProfileResponse mapItem(JsonObject item) {
+ return AiProfileResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiSetupChecksCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiSetupChecksCmd.java
new file mode 100644
index 000000000000..0b8953672272
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiSetupChecksCmd.java
@@ -0,0 +1,52 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiSetupCheckResponse;
+import org.apache.cloudstack.api.APICommand;
+
+import com.google.gson.JsonObject;
+
+/** Runs the setup wizard's preflight checks. (SPEC.md section 9). */
+@APICommand(name = ListAiSetupChecksCmd.APINAME,
+ description = "Runs the setup wizard's preflight checks.",
+ responseObject = AiSetupCheckResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class ListAiSetupChecksCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiSetupChecks";
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/setup/preflight";
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "checks";
+ }
+
+ @Override
+ protected AiSetupCheckResponse mapItem(JsonObject item) {
+ return AiSetupCheckResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiUsageCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiUsageCmd.java
new file mode 100644
index 000000000000..46d9bf3dea31
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ListAiUsageCmd.java
@@ -0,0 +1,73 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiUsageResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Lists metered usage. (SPEC.md section 9). */
+@APICommand(name = ListAiUsageCmd.APINAME,
+ description = "Lists metered usage.",
+ responseObject = AiUsageResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ListAiUsageCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "listAiUsage";
+
+ @Parameter(name = "startdate", type = CommandType.STRING,
+ description = "start of the period")
+ private String startDate;
+
+ @Parameter(name = "enddate", type = CommandType.STRING,
+ description = "end of the period")
+ private String endDate;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/usage";
+ path = withQuery(path, "start_date", startDate);
+ path = withQuery(path, "end_date", endDate);
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "usage";
+ }
+
+ @Override
+ protected AiUsageResponse mapItem(JsonObject item) {
+ return AiUsageResponse.from(item);
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+
+ @Override
+ protected String identityField() {
+ return "model";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/MirrorAiModelCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/MirrorAiModelCmd.java
new file mode 100644
index 000000000000..8ed59287fed7
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/MirrorAiModelCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Mirrors a pinned model revision into the registry. (SPEC.md section 9). */
+@APICommand(name = MirrorAiModelCmd.APINAME,
+ description = "Mirrors a pinned model revision into the registry.",
+ responseObject = AiModelResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class MirrorAiModelCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "mirrorAiModel";
+
+ @Parameter(name = "repoid", type = CommandType.STRING, required = true,
+ description = "the repository to mirror")
+ private String repoId;
+
+ @Parameter(name = "revision", type = CommandType.STRING, required = true,
+ description = "the commit to pin")
+ private String revision;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models/mirror";
+ path = withQuery(path, "repo_id", repoId);
+ path = withQuery(path, "revision", revision);
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiModelResponse response = AiModelResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_MIRROR;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "mirroring model " + repoId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PromoteAiRolloutCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PromoteAiRolloutCmd.java
new file mode 100644
index 000000000000..ff98e2d1f2b0
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PromoteAiRolloutCmd.java
@@ -0,0 +1,64 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Promotes the canary of a blue/green rollout. (SPEC.md section 9). */
+@APICommand(name = PromoteAiRolloutCmd.APINAME,
+ description = "Promotes the canary of a blue/green rollout.",
+ responseObject = AiDeploymentResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class PromoteAiRolloutCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "promoteAiRollout";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the deployment")
+ private String deploymentId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/deployments/" + deploymentId + "/rollout/promote";
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiDeploymentResponse response = AiDeploymentResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.ROLLOUT_PROMOTE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "promoting rollout of " + deploymentId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PublishAiModelCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PublishAiModelCmd.java
new file mode 100644
index 000000000000..97ddb4f47fb8
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/PublishAiModelCmd.java
@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Publishes a mirrored model to the catalog. (SPEC.md section 9). */
+@APICommand(name = PublishAiModelCmd.APINAME,
+ description = "Publishes a mirrored model to the catalog.",
+ responseObject = AiModelResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin})
+public class PublishAiModelCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "publishAiModel";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the model to publish")
+ private String modelId;
+
+ @Parameter(name = "visibility", type = CommandType.STRING,
+ description = "domains or accounts to publish to")
+ private String visibility;
+
+ @Parameter(name = "pricetier", type = CommandType.STRING,
+ description = "the price tier")
+ private String priceTier;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models/" + modelId + "/publish";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (visibility != null) {
+ body.addProperty("visibility", visibility);
+ }
+ if (priceTier != null) {
+ body.addProperty("price_tier", priceTier);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiModelResponse response = AiModelResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_PUBLISH;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "publishing model " + modelId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ReplaceAiCertificateCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ReplaceAiCertificateCmd.java
new file mode 100644
index 000000000000..811c34675b5f
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/ReplaceAiCertificateCmd.java
@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiCertificateResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Replaces a certificate, keeping its id. (SPEC.md section 9). */
+@APICommand(name = ReplaceAiCertificateCmd.APINAME,
+ description = "Replaces a certificate, keeping its id.",
+ responseObject = AiCertificateResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class ReplaceAiCertificateCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "replaceAiCertificate";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the certificate to replace")
+ private String certificateId;
+
+ @Parameter(name = "certificate", type = CommandType.STRING, required = true, length = 65535,
+ description = "the PEM certificate")
+ private String certificate;
+
+ @Parameter(name = "privatekey", type = CommandType.STRING, required = true, length = 65535,
+ description = "the PEM private key")
+ private String privateKey;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/certificates/" + certificateId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (certificate != null) {
+ body.addProperty("certificate", certificate);
+ }
+ if (privateKey != null) {
+ body.addProperty("private_key", privateKey);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiCertificateResponse response = AiCertificateResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.CERTIFICATE_REPLACE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "replacing certificate for " + certificateId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RevokeAiApiKeyCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RevokeAiApiKeyCmd.java
new file mode 100644
index 000000000000..b19c521f665c
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RevokeAiApiKeyCmd.java
@@ -0,0 +1,70 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.SuccessResponse;
+
+import com.google.gson.JsonObject;
+
+/** Revokes an API key. (SPEC.md section 9). */
+@APICommand(name = RevokeAiApiKeyCmd.APINAME,
+ description = "Revokes an API key.",
+ responseObject = SuccessResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class RevokeAiApiKeyCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "revokeAiApiKey";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the key to revoke")
+ private String keyId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/keys/" + keyId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "DELETE";
+ }
+
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ SuccessResponse response = new SuccessResponse(getCommandName());
+ response.setSuccess(true);
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.KEY_REVOKE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "revoking API key " + keyId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RollbackAiRolloutCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RollbackAiRolloutCmd.java
new file mode 100644
index 000000000000..ff5e997d04b3
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RollbackAiRolloutCmd.java
@@ -0,0 +1,64 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+/** Rolls a blue/green rollout back. (SPEC.md section 9). */
+@APICommand(name = RollbackAiRolloutCmd.APINAME,
+ description = "Rolls a blue/green rollout back.",
+ responseObject = AiDeploymentResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class RollbackAiRolloutCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "rollbackAiRollout";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the deployment")
+ private String deploymentId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/deployments/" + deploymentId + "/rollout/rollback";
+ return path;
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiDeploymentResponse response = AiDeploymentResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.ROLLOUT_ROLLBACK;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "rolling back rollout of " + deploymentId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiModelEvaluationCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiModelEvaluationCmd.java
new file mode 100644
index 000000000000..daf5f5f2757b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiModelEvaluationCmd.java
@@ -0,0 +1,79 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiEvaluationResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Records a pre-publish evaluation. (SPEC.md section 9). */
+@APICommand(name = RunAiModelEvaluationCmd.APINAME,
+ description = "Records a pre-publish evaluation.",
+ responseObject = AiEvaluationResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class RunAiModelEvaluationCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "runAiModelEvaluation";
+
+ @Parameter(name = "model", type = CommandType.STRING, required = true,
+ description = "the model evaluated")
+ private String modelName;
+
+ @Parameter(name = "revision", type = CommandType.STRING, required = true,
+ description = "the revision evaluated")
+ private String revision;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/models/" + modelName + "/evaluations";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (revision != null) {
+ body.addProperty("revision", revision);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiEvaluationResponse response = AiEvaluationResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "evaluating model " + modelName;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiSetupSelfTestCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiSetupSelfTestCmd.java
new file mode 100644
index 000000000000..241b1fb22672
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/RunAiSetupSelfTestCmd.java
@@ -0,0 +1,75 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiReconcilerRunResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Runs the setup self-test for a zone. (SPEC.md section 9). */
+@APICommand(name = RunAiSetupSelfTestCmd.APINAME,
+ description = "Runs the setup self-test for a zone.",
+ responseObject = AiReconcilerRunResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class RunAiSetupSelfTestCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "runAiSetupSelfTest";
+
+ @Parameter(name = "zoneid", type = CommandType.STRING, required = true,
+ description = "the zone to test")
+ private String zoneId;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/setup/selftest";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (zoneId != null) {
+ body.addProperty("zone", zoneId);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiReconcilerRunResponse response = AiReconcilerRunResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_DEPLOY;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "running the AI Services self-test for " + zoneId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/SearchAiHfModelsCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/SearchAiHfModelsCmd.java
new file mode 100644
index 000000000000..93daa29e4128
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/SearchAiHfModelsCmd.java
@@ -0,0 +1,63 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.api.response.AiHfModelResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Searches the Hugging Face Hub for models. (SPEC.md section 9). */
+@APICommand(name = SearchAiHfModelsCmd.APINAME,
+ description = "Searches the Hugging Face Hub for models.",
+ responseObject = AiHfModelResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class SearchAiHfModelsCmd extends AiServicesListCmd {
+
+ public static final String APINAME = "searchAiHfModels";
+
+ @Parameter(name = "query", type = CommandType.STRING, required = true,
+ description = "text to search for")
+ private String query;
+
+ @Parameter(name = "limit", type = CommandType.INTEGER,
+ description = "how many results to return")
+ private Integer limit;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/hf/search";
+ path = withQuery(path, "query", query);
+ path = withQuery(path, "limit", limit);
+ return path;
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "models";
+ }
+
+ @Override
+ protected AiHfModelResponse mapItem(JsonObject item) {
+ return AiHfModelResponse.from(item);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiBudgetCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiBudgetCmd.java
new file mode 100644
index 000000000000..d6a25f38714a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiBudgetCmd.java
@@ -0,0 +1,97 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiBudgetResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Updates a budget. (SPEC.md section 9). */
+@APICommand(name = UpdateAiBudgetCmd.APINAME,
+ description = "Updates a budget.",
+ responseObject = AiBudgetResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UpdateAiBudgetCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "updateAiBudget";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the budget to update")
+ private String budgetId;
+
+ @Parameter(name = "monthly", type = CommandType.STRING,
+ description = "the monthly limit")
+ private String monthly;
+
+ @Parameter(name = "currency", type = CommandType.STRING,
+ description = "the currency of the limit")
+ private String currency;
+
+ @Parameter(name = "onexceed", type = CommandType.STRING,
+ description = "alert or block at 100%")
+ private String onExceed;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/budgets/" + budgetId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (monthly != null) {
+ body.addProperty("monthly", monthly);
+ }
+ if (currency != null) {
+ body.addProperty("currency", currency);
+ }
+ if (onExceed != null) {
+ body.addProperty("on_exceed", onExceed);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiBudgetResponse response = AiBudgetResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.BUDGET_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "updating budget for " + budgetId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGenerationProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGenerationProfileCmd.java
new file mode 100644
index 000000000000..d7655fff2511
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGenerationProfileCmd.java
@@ -0,0 +1,83 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Updates a generation profile. (SPEC.md section 9). */
+@APICommand(name = UpdateAiGenerationProfileCmd.APINAME,
+ description = "Updates a generation profile.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UpdateAiGenerationProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "updateAiGenerationProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to update")
+ private String profileId;
+
+ @Parameter(name = "params", type = CommandType.STRING,
+ description = "parameters and policies as JSON")
+ private String params;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/generation/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (params != null) {
+ body.addProperty("params", params);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiProfileResponse response = AiProfileResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "updating generation profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGuardrailProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGuardrailProfileCmd.java
new file mode 100644
index 000000000000..e7971881bcbe
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiGuardrailProfileCmd.java
@@ -0,0 +1,83 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiGuardrailProfileResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Updates a guardrail profile. (SPEC.md section 9). */
+@APICommand(name = UpdateAiGuardrailProfileCmd.APINAME,
+ description = "Updates a guardrail profile.",
+ responseObject = AiGuardrailProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UpdateAiGuardrailProfileCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "updateAiGuardrailProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to update")
+ private String profileId;
+
+ @Parameter(name = "target", type = CommandType.STRING,
+ description = "the scope to bind it to")
+ private String target;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/guardrail/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (target != null) {
+ body.addProperty("target", target);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiGuardrailProfileResponse response = AiGuardrailProfileResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "updating guardrail profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiModelDeploymentCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiModelDeploymentCmd.java
new file mode 100644
index 000000000000..f3b98c8d7e66
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiModelDeploymentCmd.java
@@ -0,0 +1,91 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Updates an AI model deployment. (SPEC.md section 9). */
+@APICommand(name = UpdateAiModelDeploymentCmd.APINAME,
+ description = "Updates an AI model deployment.",
+ responseObject = AiDeploymentResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UpdateAiModelDeploymentCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "updateAiModelDeployment";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the deployment to update")
+ private String deploymentId;
+
+ @Parameter(name = "replicas", type = CommandType.INTEGER,
+ description = "replicas to run")
+ private Integer replicas;
+
+ @Parameter(name = "servingprofile", type = CommandType.STRING,
+ description = "the serving profile to apply")
+ private String servingProfile;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/deployments/" + deploymentId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (replicas != null) {
+ body.addProperty("replicas", replicas);
+ }
+ if (servingProfile != null) {
+ body.addProperty("serving_profile", servingProfile);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiDeploymentResponse response = AiDeploymentResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.MODEL_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "updating AI deployment " + deploymentId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiServingProfileCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiServingProfileCmd.java
new file mode 100644
index 000000000000..36618476eba1
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UpdateAiServingProfileCmd.java
@@ -0,0 +1,84 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiProfileResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Updates a serving profile, rolling it out. (SPEC.md section 9). */
+@APICommand(name = UpdateAiServingProfileCmd.APINAME,
+ description = "Updates a serving profile, rolling it out.",
+ responseObject = AiProfileResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin})
+public class UpdateAiServingProfileCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "updateAiServingProfile";
+
+ @Parameter(name = "id", type = CommandType.STRING, required = true,
+ description = "the profile to update")
+ private String profileId;
+
+ @Parameter(name = "params", type = CommandType.STRING,
+ description = "engine parameters as JSON")
+ private String params;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/profiles/serving/" + profileId;
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "PATCH";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (params != null) {
+ body.addProperty("params", params);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiProfileResponse response = AiProfileResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.PROFILE_UPDATE;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "updating serving profile " + profileId;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiAdapterCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiAdapterCmd.java
new file mode 100644
index 000000000000..aa5ebce8a601
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiAdapterCmd.java
@@ -0,0 +1,118 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiAdapterResponse;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+
+/** Registers a LoRA adapter. (SPEC.md section 9). */
+@APICommand(name = UploadAiAdapterCmd.APINAME,
+ description = "Registers a LoRA adapter.",
+ responseObject = AiAdapterResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UploadAiAdapterCmd extends AiServicesAsyncCmd {
+
+ public static final String APINAME = "uploadAiAdapter";
+
+ @Parameter(name = "name", type = CommandType.STRING, required = true,
+ description = "a name for the adapter")
+ private String name;
+
+ @Parameter(name = "basemodel", type = CommandType.STRING, required = true,
+ description = "the base it serves on")
+ private String baseModel;
+
+ @Parameter(name = "rank", type = CommandType.INTEGER, required = true,
+ description = "its LoRA rank")
+ private Integer rank;
+
+ @Parameter(name = "sizebytes", type = CommandType.INTEGER, required = true,
+ description = "size of the adapter in bytes")
+ private Integer sizeBytes;
+
+ @Parameter(name = "files", type = CommandType.STRING, required = true,
+ description = "the adapter's artefact filenames; one must be a .safetensors")
+ private String files;
+
+ @Parameter(name = "uri", type = CommandType.STRING,
+ description = "where its artefacts are")
+ private String uri;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/adapters";
+ return path;
+ }
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (name != null) {
+ body.addProperty("name", name);
+ }
+ if (baseModel != null) {
+ body.addProperty("base_model", baseModel);
+ }
+ if (rank != null) {
+ body.addProperty("rank", rank);
+ }
+ if (sizeBytes != null) {
+ body.addProperty("size_bytes", sizeBytes);
+ }
+ if (files != null) {
+ JsonArray valuesFiles = new JsonArray();
+ for (String part : files.split(",")) {
+ String trimmed = part.trim();
+ if (!trimmed.isEmpty()) {
+ valuesFiles.add(trimmed);
+ }
+ }
+ body.add("files", valuesFiles);
+ }
+ if (uri != null) {
+ body.addProperty("uri", uri);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ AiAdapterResponse response = AiAdapterResponse.from(job.getResult());
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.ADAPTER_UPLOAD;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "registering adapter " + name;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiCertificateCmd.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiCertificateCmd.java
new file mode 100644
index 000000000000..ee11154a7f3b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/command/UploadAiCertificateCmd.java
@@ -0,0 +1,93 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.command;
+
+import org.apache.cloudstack.acl.RoleType;
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiCertificateResponse;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.Parameter;
+
+import com.google.gson.JsonObject;
+
+/** Uploads a TLS certificate for a custom domain. (SPEC.md section 9). */
+@APICommand(name = UploadAiCertificateCmd.APINAME,
+ description = "Uploads a TLS certificate for a custom domain.",
+ responseObject = AiCertificateResponse.class,
+ requestHasSensitiveInfo = false,
+ responseHasSensitiveInfo = false,
+ authorized = {RoleType.Admin, RoleType.DomainAdmin, RoleType.User})
+public class UploadAiCertificateCmd extends AiServicesSyncCmd {
+
+ public static final String APINAME = "uploadAiCertificate";
+
+ @Parameter(name = "customdomain", type = CommandType.STRING, required = true,
+ description = "the domain it covers")
+ private String customDomain;
+
+ @Parameter(name = "certificate", type = CommandType.STRING, required = true, length = 65535,
+ description = "the PEM certificate")
+ private String certificate;
+
+ @Parameter(name = "privatekey", type = CommandType.STRING, required = true, length = 65535,
+ description = "the PEM private key")
+ private String privateKey;
+
+ @Override
+ protected String enginePath() {
+ String path = "/v1/certificates";
+ return path;
+ }
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+
+@Override
+ protected String engineBody() {
+ JsonObject body = new JsonObject();
+ if (customDomain != null) {
+ body.addProperty("custom_domain", customDomain);
+ }
+ if (certificate != null) {
+ body.addProperty("certificate", certificate);
+ }
+ if (privateKey != null) {
+ body.addProperty("private_key", privateKey);
+ }
+ return body.toString();
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ AiCertificateResponse response = AiCertificateResponse.from(body);
+ response.setResponseName(getCommandName());
+ setResponseObject(response);
+ }
+
+ @Override
+ public String getEventType() {
+ return AiServicesEvents.CERTIFICATE_UPLOAD;
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "uploading certificate for " + customDomain;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiAdapterResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiAdapterResponse.java
new file mode 100644
index 000000000000..55291e969359
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiAdapterResponse.java
@@ -0,0 +1,156 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A tenant's LoRA adapter (SPEC.md section 8). */
+public class AiAdapterResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the adapter's id")
+ private String id;
+
+ @SerializedName("name")
+ @Param(description = "the adapter's name")
+ private String name;
+
+ @SerializedName("basemodel")
+ @Param(description = "the base it is served on")
+ private String baseModel;
+
+ @SerializedName("servedmodelname")
+ @Param(description = "what to address it as at the gateway")
+ private String servedModelName;
+
+ @SerializedName("rank")
+ @Param(description = "its LoRA rank")
+ private Integer rank;
+
+ @SerializedName("sizebytes")
+ @Param(description = "its size on disk")
+ private Long sizeBytes;
+
+ @SerializedName("account")
+ @Param(description = "the owning account")
+ private String account;
+
+ @SerializedName("shared")
+ @Param(description = "whether it is shared across the domain")
+ private Boolean shared;
+
+ @SerializedName("created")
+ @Param(description = "when it was uploaded")
+ private String created;
+
+ /** Map one engine object onto this response. */
+ public static AiAdapterResponse from(JsonObject body) {
+ AiAdapterResponse mapped = new AiAdapterResponse();
+ mapped.setObjectName("aiadapter");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.name = readString(body, "name");
+ mapped.baseModel = readString(body, "basemodel");
+ mapped.servedModelName = readString(body, "servedmodelname");
+ mapped.rank = readInteger(body, "rank");
+ mapped.sizeBytes = readLong(body, "sizebytes");
+ mapped.account = readString(body, "account");
+ mapped.shared = readBoolean(body, "shared");
+ mapped.created = readString(body, "created");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getBaseModel() {
+ return baseModel;
+ }
+
+ public String getServedModelName() {
+ return servedModelName;
+ }
+
+ public Integer getRank() {
+ return rank;
+ }
+
+ public Long getSizeBytes() {
+ return sizeBytes;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public Boolean getShared() {
+ return shared;
+ }
+
+ public String getCreated() {
+ return created;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+
+ private static Long readLong(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsLong()
+ : null;
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponse.java
new file mode 100644
index 000000000000..b5d20283432b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponse.java
@@ -0,0 +1,114 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A scoped API key (SPEC.md section 7).
+ *
+ * The secret appears once, on creation, and never again: keys are stored
+ * as salted hashes. */
+public class AiApiKeyResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the key's identifier")
+ private String id;
+
+ @SerializedName("name")
+ @Param(description = "the operator's name for this key")
+ private String name;
+
+ @SerializedName("apikey")
+ @Param(description = "the key itself, returned only when it is created")
+ private String apiKey;
+
+ @SerializedName("allowedmodels")
+ @Param(description = "models this key may use")
+ private String allowedModels;
+
+ @SerializedName("expires")
+ @Param(description = "when the key expires")
+ private String expires;
+
+ @SerializedName("lastused")
+ @Param(description = "when the key was last used")
+ private String lastUsed;
+
+ /** Map one engine object onto this response. */
+ public static AiApiKeyResponse from(JsonObject body) {
+ AiApiKeyResponse mapped = new AiApiKeyResponse();
+ mapped.setObjectName("aiapikey");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.name = readString(body, "name");
+ mapped.apiKey = readString(body, "apikey");
+ mapped.allowedModels = readString(body, "allowedmodels");
+ mapped.expires = readString(body, "expires");
+ mapped.lastUsed = readString(body, "lastused");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getApiKey() {
+ return apiKey;
+ }
+
+ public String getAllowedModels() {
+ return allowedModels;
+ }
+
+ public String getExpires() {
+ return expires;
+ }
+
+ public String getLastUsed() {
+ return lastUsed;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBatchResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBatchResponse.java
new file mode 100644
index 000000000000..01cd13766bf0
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBatchResponse.java
@@ -0,0 +1,144 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A batch inference job (SPEC.md section 8). */
+public class AiBatchResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the batch's id")
+ private String id;
+
+ @SerializedName("model")
+ @Param(description = "the model it runs against")
+ private String model;
+
+ @SerializedName("status")
+ @Param(description = "validating, in_progress, completed, failed, expired or cancelled")
+ private String status;
+
+ @SerializedName("requestcount")
+ @Param(description = "how many requests it holds")
+ private Integer requestCount;
+
+ @SerializedName("account")
+ @Param(description = "the owning account")
+ private String account;
+
+ @SerializedName("created")
+ @Param(description = "when it was submitted")
+ private String created;
+
+ @SerializedName("finished")
+ @Param(description = "when it finished, if it has")
+ private String finished;
+
+ @SerializedName("inputuri")
+ @Param(description = "where its JSONL input came from")
+ private String inputUri;
+
+ @SerializedName("outputuri")
+ @Param(description = "where its results were written, once it has any")
+ private String outputUri;
+
+ /** Map one engine object onto this response. */
+ public static AiBatchResponse from(JsonObject body) {
+ AiBatchResponse mapped = new AiBatchResponse();
+ mapped.setObjectName("aibatch");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.model = readString(body, "model");
+ mapped.status = readString(body, "status");
+ mapped.requestCount = readInteger(body, "requestcount");
+ mapped.account = readString(body, "account");
+ mapped.created = readString(body, "created");
+ mapped.finished = readString(body, "finished");
+ mapped.inputUri = readString(body, "inputuri");
+ mapped.outputUri = readString(body, "outputuri");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public String getStatus() {
+ return status;
+ }
+
+ public Integer getRequestCount() {
+ return requestCount;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getCreated() {
+ return created;
+ }
+
+ public String getFinished() {
+ return finished;
+ }
+
+ public String getInputUri() {
+ return inputUri;
+ }
+
+ public String getOutputUri() {
+ return outputUri;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBudgetResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBudgetResponse.java
new file mode 100644
index 000000000000..66c79977df26
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiBudgetResponse.java
@@ -0,0 +1,150 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A monthly budget and where it stands (SPEC.md section 7). */
+public class AiBudgetResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the budget's identifier")
+ private String id;
+
+ @SerializedName("account")
+ @Param(description = "the account it applies to")
+ private String account;
+
+ @SerializedName("domain")
+ @Param(description = "the domain that account is in")
+ private String domain;
+
+ @SerializedName("monthly")
+ @Param(description = "the monthly limit")
+ private Double monthly;
+
+ @SerializedName("currency")
+ @Param(description = "the currency of the limit")
+ private String currency;
+
+ @SerializedName("spent")
+ @Param(description = "spend so far this month")
+ private Double spent;
+
+ @SerializedName("onexceed")
+ @Param(description = "what happens at 100%: alert or block")
+ private String onExceed;
+
+ @SerializedName("percentused")
+ @Param(description = "how much of it is used")
+ private Double percentUsed;
+
+ @SerializedName("blocked")
+ @Param(description = "whether spend is being refused")
+ private Boolean blocked;
+
+ /** Map one engine object onto this response. */
+ public static AiBudgetResponse from(JsonObject body) {
+ AiBudgetResponse mapped = new AiBudgetResponse();
+ mapped.setObjectName("aibudget");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.account = readString(body, "account");
+ mapped.domain = readString(body, "domain");
+ mapped.monthly = readDouble(body, "monthly");
+ mapped.currency = readString(body, "currency");
+ mapped.spent = readDouble(body, "spent");
+ mapped.onExceed = readString(body, "on_exceed");
+ mapped.percentUsed = readDouble(body, "percent_used");
+ mapped.blocked = readBoolean(body, "blocked");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getDomain() {
+ return domain;
+ }
+
+ public Double getMonthly() {
+ return monthly;
+ }
+
+ public String getCurrency() {
+ return currency;
+ }
+
+ public Double getSpent() {
+ return spent;
+ }
+
+ public String getOnExceed() {
+ return onExceed;
+ }
+
+ public Double getPercentUsed() {
+ return percentUsed;
+ }
+
+ public Boolean getBlocked() {
+ return blocked;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+
+ private static Double readDouble(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsDouble()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiCertificateResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiCertificateResponse.java
new file mode 100644
index 000000000000..631df5aa8be0
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiCertificateResponse.java
@@ -0,0 +1,126 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** An uploaded TLS certificate. Never carries the key or the certificate body (SPEC.md section 8). */
+public class AiCertificateResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the certificate's id")
+ private String id;
+
+ @SerializedName("customdomain")
+ @Param(description = "the domain it covers")
+ private String customDomain;
+
+ @SerializedName("fingerprint")
+ @Param(description = "its SHA-256 fingerprint")
+ private String fingerprint;
+
+ @SerializedName("expires")
+ @Param(description = "when it expires")
+ private String expires;
+
+ @SerializedName("serial")
+ @Param(description = "bumped on each replacement; a proxy built from an older one is stale")
+ private Integer serial;
+
+ @SerializedName("account")
+ @Param(description = "the owning account")
+ private String account;
+
+ @SerializedName("created")
+ @Param(description = "when it was uploaded")
+ private String created;
+
+ /** Map one engine object onto this response. */
+ public static AiCertificateResponse from(JsonObject body) {
+ AiCertificateResponse mapped = new AiCertificateResponse();
+ mapped.setObjectName("aicertificate");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.customDomain = readString(body, "customdomain");
+ mapped.fingerprint = readString(body, "fingerprint");
+ mapped.expires = readString(body, "expires");
+ mapped.serial = readInteger(body, "serial");
+ mapped.account = readString(body, "account");
+ mapped.created = readString(body, "created");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getCustomDomain() {
+ return customDomain;
+ }
+
+ public String getFingerprint() {
+ return fingerprint;
+ }
+
+ public String getExpires() {
+ return expires;
+ }
+
+ public Integer getSerial() {
+ return serial;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getCreated() {
+ return created;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiDeploymentResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiDeploymentResponse.java
new file mode 100644
index 000000000000..8072259040dd
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiDeploymentResponse.java
@@ -0,0 +1,105 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One deployment, as the engine reports it (SPEC.md section 9). */
+public class AiDeploymentResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the deployment's identifier")
+ private String id;
+
+ @SerializedName("model")
+ @Param(description = "the catalog name of the deployed model")
+ private String model;
+
+ @SerializedName("colour")
+ @Param(description = "blue or green, during a rollout")
+ private String colour;
+
+ @SerializedName("replicasdesired")
+ @Param(description = "replicas the deployment should run")
+ private Integer replicasDesired;
+
+ @SerializedName("replicasready")
+ @Param(description = "replicas currently passing their health checks")
+ private Integer replicasReady;
+
+ @SerializedName("state")
+ @Param(description = "the deployment's state as the engine reports it")
+ private String state;
+
+ /** Builds a response from an engine job result or deployment object. */
+ public static AiDeploymentResponse from(JsonObject source) {
+ AiDeploymentResponse response = new AiDeploymentResponse();
+ response.setObjectName("aideployment");
+ if (source == null) {
+ return response;
+ }
+ JsonObject body = source.has("deployment") && source.get("deployment").isJsonObject()
+ ? source.getAsJsonObject("deployment")
+ : source;
+
+ response.id = string(body, "id");
+ response.model = string(body, "model");
+ response.colour = string(body, "colour");
+ response.state = string(body, "state");
+ response.replicasDesired = integer(body, "replicas_desired");
+ response.replicasReady = integer(body, "replicas_ready");
+ return response;
+ }
+
+ private static String string(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsString()
+ : null;
+ }
+
+ private static Integer integer(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public String getColour() {
+ return colour;
+ }
+
+ public Integer getReplicasDesired() {
+ return replicasDesired;
+ }
+
+ public Integer getReplicasReady() {
+ return replicasReady;
+ }
+
+ public String getState() {
+ return state;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEffectiveParameterResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEffectiveParameterResponse.java
new file mode 100644
index 000000000000..35fc2c81446f
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEffectiveParameterResponse.java
@@ -0,0 +1,118 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One resolved generation parameter and where it came from
+ * (SPEC.md section 6). */
+public class AiEffectiveParameterResponse extends BaseResponse {
+
+ @SerializedName("name")
+ @Param(description = "the parameter")
+ private String name;
+
+ @SerializedName("value")
+ @Param(description = "the value that will be applied")
+ private String value;
+
+ @SerializedName("source")
+ @Param(description = "the precedence level that set it: platform, model, domain, account, deployment, key or request")
+ private String source;
+
+ @SerializedName("policy")
+ @Param(description = "default, clamp or locked")
+ private String policy;
+
+ @SerializedName("locked")
+ @Param(description = "whether a lower level may override it")
+ private Boolean locked;
+
+ @SerializedName("lockedat")
+ @Param(description = "the level that locked it")
+ private String lockedAt;
+
+ /** Map one engine object onto this response. */
+ public static AiEffectiveParameterResponse from(JsonObject body) {
+ AiEffectiveParameterResponse mapped = new AiEffectiveParameterResponse();
+ mapped.setObjectName("aieffectiveparameter");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.name = readString(body, "name");
+ mapped.value = readString(body, "value");
+ mapped.source = readString(body, "source");
+ mapped.policy = readString(body, "policy");
+ mapped.locked = readBoolean(body, "locked");
+ mapped.lockedAt = readString(body, "locked_at");
+ return mapped;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getValue() {
+ return value;
+ }
+
+ public String getSource() {
+ return source;
+ }
+
+ public String getPolicy() {
+ return policy;
+ }
+
+ public Boolean getLocked() {
+ return locked;
+ }
+
+ public String getLockedAt() {
+ return lockedAt;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEndpointResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEndpointResponse.java
new file mode 100644
index 000000000000..03810137729a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEndpointResponse.java
@@ -0,0 +1,118 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One OpenAI-compatible endpoint (SPEC.md section 7). */
+public class AiEndpointResponse extends BaseResponse {
+
+ @SerializedName("model")
+ @Param(description = "the model this endpoint serves")
+ private String model;
+
+ @SerializedName("baseurl")
+ @Param(description = "the OpenAI-compatible base URL")
+ private String baseUrl;
+
+ @SerializedName("task")
+ @Param(description = "chat, embedding, rerank or vision-chat")
+ private String task;
+
+ @SerializedName("pricetier")
+ @Param(description = "the price tier billed")
+ private String priceTier;
+
+ @SerializedName("snippets")
+ @Param(description = "copy-ready calls against this endpoint", responseObject = AiSnippetResponse.class)
+ private List snippets;
+
+ /** Map one engine object onto this response. */
+ public static AiEndpointResponse from(JsonObject body) {
+ AiEndpointResponse mapped = new AiEndpointResponse();
+ mapped.setObjectName("aiendpoint");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.model = readString(body, "model");
+ mapped.baseUrl = readString(body, "base_url");
+ mapped.task = readString(body, "task");
+ mapped.priceTier = readString(body, "price_tier");
+ mapped.snippets = readAiSnippetResponseList(body, "snippets");
+ return mapped;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public String getBaseUrl() {
+ return baseUrl;
+ }
+
+ public String getTask() {
+ return task;
+ }
+
+ public String getPriceTier() {
+ return priceTier;
+ }
+
+ public List getSnippets() {
+ return snippets;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static List readAiSnippetResponseList(JsonObject body, String field) {
+ List mapped = new ArrayList<>();
+ if (!body.has(field) || !body.get(field).isJsonArray()) {
+ return mapped;
+ }
+ for (JsonElement item : body.getAsJsonArray(field)) {
+ if (item.isJsonObject()) {
+ mapped.add(AiSnippetResponse.from(item.getAsJsonObject()));
+ }
+ }
+ return mapped;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEvaluationResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEvaluationResponse.java
new file mode 100644
index 000000000000..88fe9fe26ecf
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiEvaluationResponse.java
@@ -0,0 +1,117 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A pre-publish evaluation verdict (SPEC.md section 8). */
+public class AiEvaluationResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the evaluation's id")
+ private String id;
+
+ @SerializedName("model")
+ @Param(description = "the model evaluated")
+ private String model;
+
+ @SerializedName("revision")
+ @Param(description = "the revision evaluated")
+ private String revision;
+
+ @SerializedName("passed")
+ @Param(description = "whether publishing is allowed")
+ private Boolean passed;
+
+ @SerializedName("overridden")
+ @Param(description = "whether a root admin forced it through")
+ private Boolean overridden;
+
+ @SerializedName("summary")
+ @Param(description = "what the gate concluded")
+ private String summary;
+
+ /** Map one engine object onto this response. */
+ public static AiEvaluationResponse from(JsonObject body) {
+ AiEvaluationResponse mapped = new AiEvaluationResponse();
+ mapped.setObjectName("aievaluation");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.model = readString(body, "model");
+ mapped.revision = readString(body, "revision");
+ mapped.passed = readBoolean(body, "passed");
+ mapped.overridden = readBoolean(body, "overridden");
+ mapped.summary = readString(body, "summary");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public String getRevision() {
+ return revision;
+ }
+
+ public Boolean getPassed() {
+ return passed;
+ }
+
+ public Boolean getOverridden() {
+ return overridden;
+ }
+
+ public String getSummary() {
+ return summary;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuCapacityResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuCapacityResponse.java
new file mode 100644
index 000000000000..3ccba3ff96c3
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuCapacityResponse.java
@@ -0,0 +1,126 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** GPU capacity for one class in one zone (SPEC.md section 4). */
+public class AiGpuCapacityResponse extends BaseResponse {
+
+ @SerializedName("zone")
+ @Param(description = "the zone")
+ private String zone;
+
+ @SerializedName("gpuclass")
+ @Param(description = "the GPU class")
+ private String gpuClass;
+
+ @SerializedName("gpustotal")
+ @Param(description = "GPUs discovered")
+ private Integer gpusTotal;
+
+ @SerializedName("gpusfree")
+ @Param(description = "GPUs not allocated")
+ private Integer gpusFree;
+
+ @SerializedName("nodestotal")
+ @Param(description = "hosts carrying the class tag")
+ private Integer nodesTotal;
+
+ @SerializedName("nodeshealthy")
+ @Param(description = "hosts up and enabled")
+ private Integer nodesHealthy;
+
+ @SerializedName("nodesfree")
+ @Param(description = "nodes in this class with no replica on them")
+ private Integer nodesFree;
+
+ /** Map one engine object onto this response. */
+ public static AiGpuCapacityResponse from(JsonObject body) {
+ AiGpuCapacityResponse mapped = new AiGpuCapacityResponse();
+ mapped.setObjectName("aigpucapacity");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.zone = readString(body, "zone");
+ mapped.gpuClass = readString(body, "gpu_class");
+ mapped.gpusTotal = readInteger(body, "gpus_total");
+ mapped.gpusFree = readInteger(body, "gpus_free");
+ mapped.nodesTotal = readInteger(body, "nodes_total");
+ mapped.nodesHealthy = readInteger(body, "nodes_healthy");
+ mapped.nodesFree = readInteger(body, "nodes_free");
+ return mapped;
+ }
+
+ public String getZone() {
+ return zone;
+ }
+
+ public String getGpuClass() {
+ return gpuClass;
+ }
+
+ public Integer getGpusTotal() {
+ return gpusTotal;
+ }
+
+ public Integer getGpusFree() {
+ return gpusFree;
+ }
+
+ public Integer getNodesTotal() {
+ return nodesTotal;
+ }
+
+ public Integer getNodesHealthy() {
+ return nodesHealthy;
+ }
+
+ public Integer getNodesFree() {
+ return nodesFree;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuClassProposalResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuClassProposalResponse.java
new file mode 100644
index 000000000000..70b658eae1c0
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGpuClassProposalResponse.java
@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A GPU class the wizard proposes from CloudStack's host tags. */
+public class AiGpuClassProposalResponse extends BaseResponse {
+
+ @SerializedName("hosttag")
+ @Param(description = "the host tag seen")
+ private String hostTag;
+
+ @SerializedName("hosts")
+ @Param(description = "healthy hosts carrying it")
+ private Integer hosts;
+
+ @SerializedName("suggestedname")
+ @Param(description = "a name for the class")
+ private String suggestedName;
+
+ /** Map one engine object onto this response. */
+ public static AiGpuClassProposalResponse from(JsonObject body) {
+ AiGpuClassProposalResponse mapped = new AiGpuClassProposalResponse();
+ mapped.setObjectName("aigpuclassproposal");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.hostTag = readString(body, "host_tag");
+ mapped.hosts = readInteger(body, "hosts");
+ mapped.suggestedName = readString(body, "suggested_name");
+ return mapped;
+ }
+
+ public String getHostTag() {
+ return hostTag;
+ }
+
+ public Integer getHosts() {
+ return hosts;
+ }
+
+ public String getSuggestedName() {
+ return suggestedName;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailCheckResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailCheckResponse.java
new file mode 100644
index 000000000000..7553a752ea94
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailCheckResponse.java
@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One check inside a guardrail profile (SPEC.md section 8).
+ *
+ * The engine keys these by name, so the name comes from the key
+ * rather than from the object beside it. The check's own `value` —
+ * a topic list, or a size in characters — is not carried: it is a
+ * different shape per check, and what a screen needs to show is
+ * which checks apply and how strictly. */
+public class AiGuardrailCheckResponse extends BaseResponse {
+
+ @SerializedName("name")
+ @Param(description = "the check: pii, topics, input_size and so on")
+ private String name;
+
+ @SerializedName("action")
+ @Param(description = "what it does on a match: block, warn or allow")
+ private String action;
+
+ @SerializedName("policy")
+ @Param(description = "default, clamp or locked")
+ private String policy;
+
+ /** Map one engine object onto this response. */
+ public static AiGuardrailCheckResponse from(JsonObject body) {
+ AiGuardrailCheckResponse mapped = new AiGuardrailCheckResponse();
+ mapped.setObjectName("aiguardrailcheck");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.name = readString(body, "name");
+ mapped.action = readString(body, "action");
+ mapped.policy = readString(body, "policy");
+ return mapped;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getAction() {
+ return action;
+ }
+
+ public String getPolicy() {
+ return policy;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailProfileResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailProfileResponse.java
new file mode 100644
index 000000000000..40661bba4d4b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiGuardrailProfileResponse.java
@@ -0,0 +1,122 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A guardrail profile and where it is bound (SPEC.md sections 6, 8). */
+public class AiGuardrailProfileResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the profile's id")
+ private String id;
+
+ @SerializedName("name")
+ @Param(description = "the profile's name")
+ private String name;
+
+ @SerializedName("scope")
+ @Param(description = "the level it is bound at")
+ private String scope;
+
+ @SerializedName("target")
+ @Param(description = "the domain, account or deployment")
+ private String target;
+
+ @SerializedName("checks")
+ @Param(description = "the checks this profile applies", responseObject = AiGuardrailCheckResponse.class)
+ private List checks;
+
+ /** Map one engine object onto this response. */
+ public static AiGuardrailProfileResponse from(JsonObject body) {
+ AiGuardrailProfileResponse mapped = new AiGuardrailProfileResponse();
+ mapped.setObjectName("aiguardrailprofile");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.name = readString(body, "name");
+ mapped.scope = readString(body, "scope");
+ mapped.target = readString(body, "target");
+ mapped.checks = readAiGuardrailCheckResponseMap(body, "checks");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getScope() {
+ return scope;
+ }
+
+ public String getTarget() {
+ return target;
+ }
+
+ public List getChecks() {
+ return checks;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static List readAiGuardrailCheckResponseMap(JsonObject body, String field) {
+ List mapped = new ArrayList<>();
+ if (!body.has(field) || !body.get(field).isJsonObject()) {
+ return mapped;
+ }
+ for (Map.Entry entry : body.getAsJsonObject(field).entrySet()) {
+ if (!entry.getValue().isJsonObject()) {
+ continue;
+ }
+ JsonObject named = entry.getValue().getAsJsonObject().deepCopy();
+ named.addProperty("name", entry.getKey());
+ mapped.add(AiGuardrailCheckResponse.from(named));
+ }
+ return mapped;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfCheckResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfCheckResponse.java
new file mode 100644
index 000000000000..c4995854d376
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfCheckResponse.java
@@ -0,0 +1,156 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A model compatibility report (SPEC.md section 5, step 2). */
+public class AiHfCheckResponse extends BaseResponse {
+
+ @SerializedName("repoid")
+ @Param(description = "the repository checked")
+ private String repoId;
+
+ @SerializedName("revision")
+ @Param(description = "the commit the report is for")
+ private String revision;
+
+ @SerializedName("compatible")
+ @Param(description = "whether this model can be served")
+ private Boolean compatible;
+
+ @SerializedName("architecture")
+ @Param(description = "the architecture from config.json")
+ private String architecture;
+
+ @SerializedName("license")
+ @Param(description = "the declared licence")
+ private String license;
+
+ @SerializedName("downloadbytes")
+ @Param(description = "bytes to mirror")
+ private Long downloadBytes;
+
+ @SerializedName("contextlength")
+ @Param(description = "the model's maximum context length")
+ private Integer contextLength;
+
+ @SerializedName("gated")
+ @Param(description = "whether the repo is gated")
+ private Boolean gated;
+
+ @SerializedName("requiresremotecode")
+ @Param(description = "whether the repo ships its own modelling code")
+ private Boolean requiresRemoteCode;
+
+ /** Map one engine object onto this response. */
+ public static AiHfCheckResponse from(JsonObject body) {
+ AiHfCheckResponse mapped = new AiHfCheckResponse();
+ mapped.setObjectName("aihfcheck");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.repoId = readString(body, "repo_id");
+ mapped.revision = readString(body, "revision");
+ mapped.compatible = readBoolean(body, "compatible");
+ mapped.architecture = readString(body, "architecture");
+ mapped.license = readString(body, "license");
+ mapped.downloadBytes = readLong(body, "download_bytes");
+ mapped.contextLength = readInteger(body, "context_length");
+ mapped.gated = readBoolean(body, "gated");
+ mapped.requiresRemoteCode = readBoolean(body, "requires_remote_code");
+ return mapped;
+ }
+
+ public String getRepoId() {
+ return repoId;
+ }
+
+ public String getRevision() {
+ return revision;
+ }
+
+ public Boolean getCompatible() {
+ return compatible;
+ }
+
+ public String getArchitecture() {
+ return architecture;
+ }
+
+ public String getLicense() {
+ return license;
+ }
+
+ public Long getDownloadBytes() {
+ return downloadBytes;
+ }
+
+ public Integer getContextLength() {
+ return contextLength;
+ }
+
+ public Boolean getGated() {
+ return gated;
+ }
+
+ public Boolean getRequiresRemoteCode() {
+ return requiresRemoteCode;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Integer readInteger(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsInt()
+ : null;
+ }
+
+ private static Long readLong(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsLong()
+ : null;
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfModelResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfModelResponse.java
new file mode 100644
index 000000000000..5173c91ba8db
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiHfModelResponse.java
@@ -0,0 +1,99 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One Hugging Face repo from a search (SPEC.md section 5). */
+public class AiHfModelResponse extends BaseResponse {
+
+ @SerializedName("repoid")
+ @Param(description = "the Hugging Face repository id")
+ private String repoId;
+
+ @SerializedName("license")
+ @Param(description = "the repo's declared licence")
+ private String license;
+
+ @SerializedName("task")
+ @Param(description = "the repo's pipeline task")
+ private String task;
+
+ @SerializedName("gated")
+ @Param(description = "whether the licence must be accepted on Hugging Face first")
+ private Boolean gated;
+
+ /** Map one engine object onto this response. */
+ public static AiHfModelResponse from(JsonObject body) {
+ AiHfModelResponse mapped = new AiHfModelResponse();
+ mapped.setObjectName("aihfmodel");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.repoId = readString(body, "repo_id");
+ mapped.license = readString(body, "license");
+ mapped.task = readString(body, "task");
+ mapped.gated = readBoolean(body, "gated");
+ return mapped;
+ }
+
+ public String getRepoId() {
+ return repoId;
+ }
+
+ public String getLicense() {
+ return license;
+ }
+
+ public String getTask() {
+ return task;
+ }
+
+ public Boolean getGated() {
+ return gated;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiModelResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiModelResponse.java
new file mode 100644
index 000000000000..47798b4356a2
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiModelResponse.java
@@ -0,0 +1,118 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.google.gson.JsonObject;
+
+import com.cloud.serializer.Param;
+import com.google.gson.annotations.SerializedName;
+
+/** One catalog entry, as listAiModels returns it (SPEC.md section 9). */
+public class AiModelResponse extends BaseResponse {
+
+ @SerializedName("name")
+ @Param(description = "the catalog name tenants address the model by")
+ private String name;
+
+ @SerializedName("task")
+ @Param(description = "chat, embedding, rerank or vision-chat")
+ private String task;
+
+ @SerializedName("engine")
+ @Param(description = "the serving engine: vllm, sglang or trtllm")
+ private String engine;
+
+ @SerializedName("license")
+ @Param(description = "the model's licence, which must be on the allow-list")
+ private String license;
+
+ @SerializedName("pricetier")
+ @Param(description = "the price tier this model is billed under")
+ private String priceTier;
+
+ @SerializedName("maxmodellen")
+ @Param(description = "the maximum context length in tokens")
+ private Integer maxModelLen;
+
+ @SerializedName("mirrored")
+ @Param(description = "whether the weights are mirrored and the model can be deployed")
+ private Boolean mirrored;
+
+ /** Map one engine model object onto this response. */
+ public static AiModelResponse from(JsonObject body) {
+ AiModelResponse mapped = new AiModelResponse();
+ mapped.setObjectName("aimodel");
+ if (body == null) {
+ return mapped;
+ }
+ JsonObject source = body.has("model") && body.get("model").isJsonObject()
+ ? body.getAsJsonObject("model")
+ : body;
+ mapped.name = text(source, "name");
+ mapped.task = text(source, "task");
+ mapped.engine = text(source, "engine");
+ mapped.license = text(source, "license");
+ mapped.priceTier = text(source, "price_tier");
+ if (source.has("max_model_len") && !source.get("max_model_len").isJsonNull()) {
+ mapped.maxModelLen = source.get("max_model_len").getAsInt();
+ }
+ mapped.mirrored = source.has("mirrored") && source.get("mirrored").getAsBoolean();
+ return mapped;
+ }
+
+ private static String text(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsString()
+ : null;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public void setTask(String task) {
+ this.task = task;
+ }
+
+ public void setEngine(String engine) {
+ this.engine = engine;
+ }
+
+ public void setLicense(String license) {
+ this.license = license;
+ }
+
+ public void setPriceTier(String priceTier) {
+ this.priceTier = priceTier;
+ }
+
+ public void setMaxModelLen(Integer maxModelLen) {
+ this.maxModelLen = maxModelLen;
+ }
+
+ public void setMirrored(Boolean mirrored) {
+ this.mirrored = mirrored;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public Boolean getMirrored() {
+ return mirrored;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPlaygroundSessionResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPlaygroundSessionResponse.java
new file mode 100644
index 000000000000..df2bcfc21357
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPlaygroundSessionResponse.java
@@ -0,0 +1,105 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** An ephemeral playground session (SPEC.md section 7).
+ *
+ * The key is model-scoped and expires in fifteen minutes, so a real
+ * key never reaches the browser. */
+public class AiPlaygroundSessionResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the session key's identifier")
+ private String id;
+
+ @SerializedName("sessionkey")
+ @Param(description = "the short-lived, model-scoped key")
+ private String sessionKey;
+
+ @SerializedName("model")
+ @Param(description = "the model this session may use")
+ private String model;
+
+ @SerializedName("baseurl")
+ @Param(description = "the endpoint to call")
+ private String baseUrl;
+
+ @SerializedName("expires")
+ @Param(description = "when the session key expires")
+ private String expires;
+
+ /** Map one engine object onto this response. */
+ public static AiPlaygroundSessionResponse from(JsonObject body) {
+ AiPlaygroundSessionResponse mapped = new AiPlaygroundSessionResponse();
+ mapped.setObjectName("aiplaygroundsession");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.sessionKey = readString(body, "apikey");
+ mapped.model = readString(body, "model");
+ mapped.baseUrl = readString(body, "base_url");
+ mapped.expires = readString(body, "expires");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getSessionKey() {
+ return sessionKey;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public String getBaseUrl() {
+ return baseUrl;
+ }
+
+ public String getExpires() {
+ return expires;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPrivateEndpointResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPrivateEndpointResponse.java
new file mode 100644
index 000000000000..b4a5eea587a6
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiPrivateEndpointResponse.java
@@ -0,0 +1,153 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** How a deployment is exposed (SPEC.md section 8). */
+public class AiPrivateEndpointResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the exposure's id")
+ private String id;
+
+ @SerializedName("deployment")
+ @Param(description = "the deployment it fronts")
+ private String deployment;
+
+ @SerializedName("exposure")
+ @Param(description = "in words: public, private, or both")
+ private String exposure;
+
+ @SerializedName("network")
+ @Param(description = "the tier the private endpoint sits on")
+ private String network;
+
+ @SerializedName("publicenabled")
+ @Param(description = "whether it is also reachable publicly")
+ private Boolean publicEnabled;
+
+ @SerializedName("customdomain")
+ @Param(description = "the domain it answers on, if any")
+ private String customDomain;
+
+ @SerializedName("tls")
+ @Param(description = "where its certificate comes from: none, acme or uploaded")
+ private String tls;
+
+ @SerializedName("certificate")
+ @Param(description = "the uploaded certificate it uses, if any")
+ private String certificate;
+
+ @SerializedName("account")
+ @Param(description = "the owning account")
+ private String account;
+
+ @SerializedName("created")
+ @Param(description = "when it was created")
+ private String created;
+
+ /** Map one engine object onto this response. */
+ public static AiPrivateEndpointResponse from(JsonObject body) {
+ AiPrivateEndpointResponse mapped = new AiPrivateEndpointResponse();
+ mapped.setObjectName("aiprivateendpoint");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.deployment = readString(body, "deployment");
+ mapped.exposure = readString(body, "exposure");
+ mapped.network = readString(body, "network");
+ mapped.publicEnabled = readBoolean(body, "publicenabled");
+ mapped.customDomain = readString(body, "customdomain");
+ mapped.tls = readString(body, "tls");
+ mapped.certificate = readString(body, "certificate");
+ mapped.account = readString(body, "account");
+ mapped.created = readString(body, "created");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getDeployment() {
+ return deployment;
+ }
+
+ public String getExposure() {
+ return exposure;
+ }
+
+ public String getNetwork() {
+ return network;
+ }
+
+ public Boolean getPublicEnabled() {
+ return publicEnabled;
+ }
+
+ public String getCustomDomain() {
+ return customDomain;
+ }
+
+ public String getTls() {
+ return tls;
+ }
+
+ public String getCertificate() {
+ return certificate;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getCreated() {
+ return created;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiProfileResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiProfileResponse.java
new file mode 100644
index 000000000000..e895503f0543
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiProfileResponse.java
@@ -0,0 +1,102 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A tuning profile (SPEC.md section 6). */
+public class AiProfileResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the profile's identifier")
+ private String id;
+
+ @SerializedName("name")
+ @Param(description = "the profile's name")
+ private String name;
+
+ @SerializedName("kind")
+ @Param(description = "serving, generation or guardrail")
+ private String kind;
+
+ @SerializedName("scope")
+ @Param(description = "the scope this profile is assigned at")
+ private String scope;
+
+ @SerializedName("target")
+ @Param(description = "what the assignment applies to")
+ private String target;
+
+ /** Map one engine object onto this response. */
+ public static AiProfileResponse from(JsonObject body) {
+ AiProfileResponse mapped = new AiProfileResponse();
+ mapped.setObjectName("aiprofile");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.name = readString(body, "name");
+ mapped.kind = readString(body, "kind");
+ mapped.scope = readString(body, "scope");
+ mapped.target = readString(body, "target");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getKind() {
+ return kind;
+ }
+
+ public String getScope() {
+ return scope;
+ }
+
+ public String getTarget() {
+ return target;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerActionResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerActionResponse.java
new file mode 100644
index 000000000000..80fca5c57a85
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerActionResponse.java
@@ -0,0 +1,105 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One action inside a reconcile run (SPEC.md section 4).
+ *
+ * A failed action stops only its dependants, so a run can be part
+ * applied and the outcome per action is what says how far it got. */
+public class AiReconcilerActionResponse extends BaseResponse {
+
+ @SerializedName("kind")
+ @Param(description = "what was done: create, update, delete")
+ private String kind;
+
+ @SerializedName("resourcetype")
+ @Param(description = "the kind of thing it was done to")
+ private String resourceType;
+
+ @SerializedName("name")
+ @Param(description = "which one")
+ private String name;
+
+ @SerializedName("outcome")
+ @Param(description = "succeeded, failed or skipped")
+ private String outcome;
+
+ @SerializedName("error")
+ @Param(description = "why it failed, where it did")
+ private String error;
+
+ /** Map one engine object onto this response. */
+ public static AiReconcilerActionResponse from(JsonObject body) {
+ AiReconcilerActionResponse mapped = new AiReconcilerActionResponse();
+ mapped.setObjectName("aireconcileraction");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.kind = readString(body, "kind");
+ mapped.resourceType = readString(body, "resource_type");
+ mapped.name = readString(body, "name");
+ mapped.outcome = readString(body, "outcome");
+ mapped.error = readString(body, "error");
+ return mapped;
+ }
+
+ public String getKind() {
+ return kind;
+ }
+
+ public String getResourceType() {
+ return resourceType;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getOutcome() {
+ return outcome;
+ }
+
+ public String getError() {
+ return error;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerRunResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerRunResponse.java
new file mode 100644
index 000000000000..30ff3185584a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiReconcilerRunResponse.java
@@ -0,0 +1,142 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One reconciler run (SPEC.md section 4). */
+public class AiReconcilerRunResponse extends BaseResponse {
+
+ @SerializedName("id")
+ @Param(description = "the run's identifier")
+ private String id;
+
+ @SerializedName("zone")
+ @Param(description = "the zone reconciled")
+ private String zone;
+
+ @SerializedName("status")
+ @Param(description = "running, succeeded or failed")
+ private String status;
+
+ @SerializedName("dryrun")
+ @Param(description = "whether the run wrote anything")
+ private Boolean dryRun;
+
+ @SerializedName("startedat")
+ @Param(description = "when the run began")
+ private String startedAt;
+
+ @SerializedName("finishedat")
+ @Param(description = "when the run ended")
+ private String finishedAt;
+
+ @SerializedName("actions")
+ @Param(description = "what the run did, in order", responseObject = AiReconcilerActionResponse.class)
+ private List actions;
+
+ /** Map one engine object onto this response. */
+ public static AiReconcilerRunResponse from(JsonObject body) {
+ AiReconcilerRunResponse mapped = new AiReconcilerRunResponse();
+ mapped.setObjectName("aireconcilerrun");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.id = readString(body, "id");
+ mapped.zone = readString(body, "zone");
+ mapped.status = readString(body, "status");
+ mapped.dryRun = readBoolean(body, "dry_run");
+ mapped.startedAt = readString(body, "started_at");
+ mapped.finishedAt = readString(body, "finished_at");
+ mapped.actions = readAiReconcilerActionResponseList(body, "actions");
+ return mapped;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getZone() {
+ return zone;
+ }
+
+ public String getStatus() {
+ return status;
+ }
+
+ public Boolean getDryRun() {
+ return dryRun;
+ }
+
+ public String getStartedAt() {
+ return startedAt;
+ }
+
+ public String getFinishedAt() {
+ return finishedAt;
+ }
+
+ public List getActions() {
+ return actions;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Boolean readBoolean(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsBoolean()
+ : null;
+ }
+
+ private static List readAiReconcilerActionResponseList(JsonObject body, String field) {
+ List mapped = new ArrayList<>();
+ if (!body.has(field) || !body.get(field).isJsonArray()) {
+ return mapped;
+ }
+ for (JsonElement item : body.getAsJsonArray(field)) {
+ if (item.isJsonObject()) {
+ mapped.add(AiReconcilerActionResponse.from(item.getAsJsonObject()));
+ }
+ }
+ return mapped;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSetupCheckResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSetupCheckResponse.java
new file mode 100644
index 000000000000..bf76455a22fe
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSetupCheckResponse.java
@@ -0,0 +1,93 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** One preflight check from the setup wizard (SPEC.md section 7). */
+public class AiSetupCheckResponse extends BaseResponse {
+
+ @SerializedName("name")
+ @Param(description = "what was checked")
+ private String name;
+
+ @SerializedName("status")
+ @Param(description = "pass, warn, fail or skipped")
+ private String status;
+
+ @SerializedName("detail")
+ @Param(description = "what was found")
+ private String detail;
+
+ @SerializedName("remedy")
+ @Param(description = "what to do about it, where the check did not pass")
+ private String remedy;
+
+ /** Map one engine object onto this response. */
+ public static AiSetupCheckResponse from(JsonObject body) {
+ AiSetupCheckResponse mapped = new AiSetupCheckResponse();
+ mapped.setObjectName("aisetupcheck");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.name = readString(body, "name");
+ mapped.status = readString(body, "status");
+ mapped.detail = readString(body, "detail");
+ mapped.remedy = readString(body, "remedy");
+ return mapped;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getStatus() {
+ return status;
+ }
+
+ public String getDetail() {
+ return detail;
+ }
+
+ public String getRemedy() {
+ return remedy;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSnippetResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSnippetResponse.java
new file mode 100644
index 000000000000..888b09497d4a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiSnippetResponse.java
@@ -0,0 +1,89 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** A copy-ready call against one endpoint (SPEC.md section 7).
+ *
+ * Rendered by the engine, so there is one implementation of
+ * "how you call this". It reads the key from the environment
+ * rather than carrying one: a snippet is copied into tickets and
+ * chats, where a live key would outlive any session. */
+public class AiSnippetResponse extends BaseResponse {
+
+ @SerializedName("name")
+ @Param(description = "what this snippet shows")
+ private String name;
+
+ @SerializedName("language")
+ @Param(description = "the language it is written in")
+ private String language;
+
+ @SerializedName("code")
+ @Param(description = "the snippet itself")
+ private String code;
+
+ /** Map one engine object onto this response. */
+ public static AiSnippetResponse from(JsonObject body) {
+ AiSnippetResponse mapped = new AiSnippetResponse();
+ mapped.setObjectName("aisnippet");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.name = readString(body, "name");
+ mapped.language = readString(body, "language");
+ mapped.code = readString(body, "code");
+ return mapped;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public String getLanguage() {
+ return language;
+ }
+
+ public String getCode() {
+ return code;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiUsageResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiUsageResponse.java
new file mode 100644
index 000000000000..4f353a168306
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/api/response/AiUsageResponse.java
@@ -0,0 +1,132 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+// GENERATED by tools/generate_commands.py from SPEC.md section 9's command
+// map. Edit the generator, not this file.
+package org.apache.cloudstack.ai.api.response;
+
+import org.apache.cloudstack.api.BaseResponse;
+
+import com.cloud.serializer.Param;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
+
+/** Metered usage for one tenant and model (SPEC.md section 7). */
+public class AiUsageResponse extends BaseResponse {
+
+ @SerializedName("account")
+ @Param(description = "the account billed")
+ private String account;
+
+ @SerializedName("model")
+ @Param(description = "the model used")
+ private String model;
+
+ @SerializedName("inputtokens")
+ @Param(description = "input tokens")
+ private Long inputTokens;
+
+ @SerializedName("outputtokens")
+ @Param(description = "output tokens")
+ private Long outputTokens;
+
+ @SerializedName("gpuhours")
+ @Param(description = "GPU hours consumed")
+ private Double gpuHours;
+
+ @SerializedName("cost")
+ @Param(description = "spend in the tier's currency")
+ private Double cost;
+
+ @SerializedName("currency")
+ @Param(description = "the currency of the cost")
+ private String currency;
+
+ /** Map one engine object onto this response. */
+ public static AiUsageResponse from(JsonObject body) {
+ AiUsageResponse mapped = new AiUsageResponse();
+ mapped.setObjectName("aiusage");
+ if (body == null) {
+ return mapped;
+ }
+ mapped.account = readString(body, "account");
+ mapped.model = readString(body, "model");
+ mapped.inputTokens = readLong(body, "input_tokens");
+ mapped.outputTokens = readLong(body, "output_tokens");
+ mapped.gpuHours = readDouble(body, "gpu_hours");
+ mapped.cost = readDouble(body, "cost");
+ mapped.currency = readString(body, "currency");
+ return mapped;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getModel() {
+ return model;
+ }
+
+ public Long getInputTokens() {
+ return inputTokens;
+ }
+
+ public Long getOutputTokens() {
+ return outputTokens;
+ }
+
+ public Double getGpuHours() {
+ return gpuHours;
+ }
+
+ public Double getCost() {
+ return cost;
+ }
+
+ public String getCurrency() {
+ return currency;
+ }
+
+ private static String readString(JsonObject body, String field) {
+ if (!body.has(field) || body.get(field).isJsonNull()) {
+ return null;
+ }
+ JsonElement value = body.get(field);
+ if (!value.isJsonArray()) {
+ return value.getAsString();
+ }
+ StringBuilder joined = new StringBuilder();
+ for (JsonElement part : value.getAsJsonArray()) {
+ if (joined.length() > 0) {
+ joined.append(",");
+ }
+ joined.append(part.getAsString());
+ }
+ return joined.toString();
+ }
+
+ private static Long readLong(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsLong()
+ : null;
+ }
+
+ private static Double readDouble(JsonObject body, String field) {
+ return body.has(field) && !body.get(field).isJsonNull()
+ ? body.get(field).getAsDouble()
+ : null;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDao.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDao.java
new file mode 100644
index 000000000000..e7ce10239803
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDao.java
@@ -0,0 +1,41 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.dao;
+
+import java.util.List;
+
+import com.cloud.utils.db.GenericDao;
+
+/** Ownership rows for AI deployments (SPEC.md section 9). */
+public interface AiDeploymentDao extends GenericDao {
+
+ List listByAccount(long accountId);
+
+ List listByDomain(long domainId);
+
+ List listByZone(long zoneId);
+
+ AiDeploymentVO findByEngineId(String engineId);
+
+ /**
+ * Remove every deployment owned by an account.
+ *
+ * Called from the account deletion hook, so a deleted account leaves
+ * nothing behind (SPEC.md section 9).
+ *
+ * @return how many rows were removed.
+ */
+ int removeByAccount(long accountId);
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDaoImpl.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDaoImpl.java
new file mode 100644
index 000000000000..a80281c5d81b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentDaoImpl.java
@@ -0,0 +1,84 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.dao;
+
+import java.util.List;
+
+import com.cloud.utils.db.GenericDaoBase;
+import com.cloud.utils.db.SearchBuilder;
+import com.cloud.utils.db.SearchCriteria;
+
+/** The ownership DAO, built on CloudStack's own search machinery. */
+public class AiDeploymentDaoImpl
+ extends GenericDaoBase implements AiDeploymentDao {
+
+ private final SearchBuilder byAccount;
+ private final SearchBuilder byDomain;
+ private final SearchBuilder byZone;
+ private final SearchBuilder byEngineId;
+
+ public AiDeploymentDaoImpl() {
+ byAccount = createSearchBuilder();
+ byAccount.and("accountId", byAccount.entity().getAccountId(), SearchCriteria.Op.EQ);
+ byAccount.done();
+
+ byDomain = createSearchBuilder();
+ byDomain.and("domainId", byDomain.entity().getDomainId(), SearchCriteria.Op.EQ);
+ byDomain.done();
+
+ byZone = createSearchBuilder();
+ byZone.and("zoneId", byZone.entity().getZoneId(), SearchCriteria.Op.EQ);
+ byZone.done();
+
+ byEngineId = createSearchBuilder();
+ byEngineId.and("engineId", byEngineId.entity().getEngineId(), SearchCriteria.Op.EQ);
+ byEngineId.done();
+ }
+
+ @Override
+ public List listByAccount(long accountId) {
+ SearchCriteria search = byAccount.create();
+ search.setParameters("accountId", accountId);
+ return listBy(search);
+ }
+
+ @Override
+ public List listByDomain(long domainId) {
+ SearchCriteria search = byDomain.create();
+ search.setParameters("domainId", domainId);
+ return listBy(search);
+ }
+
+ @Override
+ public List listByZone(long zoneId) {
+ SearchCriteria search = byZone.create();
+ search.setParameters("zoneId", zoneId);
+ return listBy(search);
+ }
+
+ @Override
+ public AiDeploymentVO findByEngineId(String engineId) {
+ SearchCriteria search = byEngineId.create();
+ search.setParameters("engineId", engineId);
+ return findOneBy(search);
+ }
+
+ @Override
+ public int removeByAccount(long accountId) {
+ SearchCriteria search = byAccount.create();
+ search.setParameters("accountId", accountId);
+ return remove(search);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentVO.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentVO.java
new file mode 100644
index 000000000000..3e6da148287e
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/dao/AiDeploymentVO.java
@@ -0,0 +1,143 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.dao;
+
+import java.util.Date;
+import java.util.UUID;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+import javax.persistence.Table;
+
+import org.apache.cloudstack.api.Identity;
+import org.apache.cloudstack.api.InternalIdentity;
+
+/**
+ * The ownership row for one deployment (SPEC.md section 9).
+ *
+ * Deliberately minimal: uuid, owner, zone and the engine's identifier.
+ * The engine stays the source of truth for runtime state — replicas,
+ * health, rollouts — and duplicating it here would create two answers to
+ * the same question. What this buys is everything CloudStack does
+ * natively with an owned row: ownership checks, list filtering by
+ * account and domain, and cleanup when either is deleted.
+ */
+@Entity
+@Table(name = "ai_deployment")
+public class AiDeploymentVO implements InternalIdentity, Identity {
+
+ @Id
+ @GeneratedValue(strategy = GenerationType.IDENTITY)
+ @Column(name = "id")
+ private long id;
+
+ @Column(name = "uuid")
+ private String uuid;
+
+ @Column(name = "name")
+ private String name;
+
+ @Column(name = "account_id")
+ private long accountId;
+
+ @Column(name = "domain_id")
+ private long domainId;
+
+ @Column(name = "zone_id")
+ private long zoneId;
+
+ @Column(name = "engine_id")
+ private String engineId;
+
+ @Column(name = "state")
+ private String state;
+
+ @Column(name = "created")
+ private Date created;
+
+ @Column(name = "removed")
+ private Date removed;
+
+ protected AiDeploymentVO() {
+ this.uuid = UUID.randomUUID().toString();
+ }
+
+ public AiDeploymentVO(
+ String name, long accountId, long domainId, long zoneId, String engineId) {
+ this.uuid = UUID.randomUUID().toString();
+ this.name = name;
+ this.accountId = accountId;
+ this.domainId = domainId;
+ this.zoneId = zoneId;
+ this.engineId = engineId;
+ this.state = "Allocated";
+ this.created = new Date();
+ }
+
+ @Override
+ public long getId() {
+ return id;
+ }
+
+ @Override
+ public String getUuid() {
+ return uuid;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public long getAccountId() {
+ return accountId;
+ }
+
+ public long getDomainId() {
+ return domainId;
+ }
+
+ public long getZoneId() {
+ return zoneId;
+ }
+
+ public String getEngineId() {
+ return engineId;
+ }
+
+ public String getState() {
+ return state;
+ }
+
+ public void setState(String state) {
+ this.state = state;
+ }
+
+ public Date getCreated() {
+ return created;
+ }
+
+ public Date getRemoved() {
+ return removed;
+ }
+
+ @Override
+ public String toString() {
+ return "AiDeployment{uuid=" + uuid + ", name=" + name
+ + ", account=" + accountId + ", zone=" + zoneId + "}";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/CallerContext.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/CallerContext.java
new file mode 100644
index 000000000000..7735e9d7a18a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/CallerContext.java
@@ -0,0 +1,128 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Who is calling, taken from the CloudStack session (SPEC.md section 10).
+ *
+ * The engine authenticates nobody: it is unreachable from tenant networks
+ * and requires a client certificate, and this assertion is what it filters
+ * every response by. Building it anywhere other than from a real
+ * {@code CallContext} would hand a caller someone else's data.
+ */
+public final class CallerContext {
+
+ public static final String USER_HEADER = "X-Aisvc-User-Id";
+ public static final String ACCOUNT_HEADER = "X-Aisvc-Account";
+ public static final String DOMAIN_HEADER = "X-Aisvc-Domain";
+ public static final String ROLE_HEADER = "X-Aisvc-Role";
+
+ /** The role the engine treats as seeing everything. */
+ public static final String ROLE_ADMIN = "Admin";
+
+ private final String userId;
+ private final String account;
+ private final String domainPath;
+ private final String role;
+
+ public CallerContext(String userId, String account, String domainPath, String role) {
+ this.userId = require(userId, "userId");
+ this.account = require(account, "account");
+ this.domainPath = require(domainPath, "domainPath");
+ this.role = require(role, "role");
+ }
+
+ /**
+ * The plugin acting on its own behalf, not for any user.
+ *
+ *
Used only where there is no CloudStack session to build a context
+ * from and the work is the platform's own — host maintenance draining a
+ * GPU node, for instance. It is deliberately a separate factory rather
+ * than a default: a context for a tenant request must always come from
+ * {@code CallContext}, never from a fallback, because the engine filters
+ * every response by whatever the plugin asserts here.
+ */
+ public static CallerContext system() {
+ return new CallerContext("system", "system", "/", ROLE_ADMIN);
+ }
+
+ /** Whether this caller sees the whole platform rather than one account. */
+ public boolean isAdmin() {
+ return ROLE_ADMIN.equalsIgnoreCase(role);
+ }
+
+ private static String require(String value, String field) {
+ if (value == null || value.trim().isEmpty()) {
+ throw new IllegalArgumentException(field + " is required in the caller context");
+ }
+ return value;
+ }
+
+ public Map asHeaders() {
+ Map headers = new LinkedHashMap<>();
+ headers.put(USER_HEADER, userId);
+ headers.put(ACCOUNT_HEADER, account);
+ headers.put(DOMAIN_HEADER, domainPath);
+ headers.put(ROLE_HEADER, role);
+ return headers;
+ }
+
+ public String getUserId() {
+ return userId;
+ }
+
+ public String getAccount() {
+ return account;
+ }
+
+ public String getDomainPath() {
+ return domainPath;
+ }
+
+ public String getRole() {
+ return role;
+ }
+
+ @Override
+ public boolean equals(Object other) {
+ if (this == other) {
+ return true;
+ }
+ if (!(other instanceof CallerContext)) {
+ return false;
+ }
+ CallerContext that = (CallerContext) other;
+ return userId.equals(that.userId)
+ && account.equals(that.account)
+ && domainPath.equals(that.domainPath)
+ && role.equals(that.role);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(userId, account, domainPath, role);
+ }
+
+ /** Deliberately omits nothing sensitive; none of these are secrets. */
+ @Override
+ public String toString() {
+ return "CallerContext{user=" + userId + ", account=" + account
+ + ", domain=" + domainPath + ", role=" + role + "}";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineClient.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineClient.java
new file mode 100644
index 000000000000..662aefcbe36a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineClient.java
@@ -0,0 +1,130 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Calls the AI Services engine REST API (SPEC.md sections 7 and 10).
+ *
+ * Two behaviours matter and are the reason this is a class rather than a
+ * bare HTTP call:
+ *
+ *
+ *
Failover. "The Java plugin accepts multiple engine URLs and
+ * fails over between them" (section 7). A replica that cannot be
+ * reached is skipped; a replica that answers — even with an error —
+ * has answered, and its answer is returned rather than retried
+ * elsewhere, because retrying a POST against the next replica could
+ * do the work twice.
+ *
Caller context. Every request carries the CloudStack
+ * session's identity, which the engine filters responses by.
+ *
+ *
+ * The transport is injected so the failover logic can be tested without a
+ * socket; {@link HttpEngineTransport} is the mTLS implementation.
+ */
+public class EngineClient {
+
+ private final List baseUrls;
+ private final EngineTransport transport;
+
+ public EngineClient(List baseUrls, EngineTransport transport) {
+ List cleaned = new ArrayList<>();
+ for (String url : baseUrls) {
+ if (url != null && !url.trim().isEmpty()) {
+ cleaned.add(stripTrailingSlash(url.trim()));
+ }
+ }
+ if (cleaned.isEmpty()) {
+ throw new IllegalArgumentException(
+ "at least one engine URL is required; set ai.services.engine.urls");
+ }
+ this.baseUrls = Collections.unmodifiableList(cleaned);
+ this.transport = transport;
+ }
+
+ /** Parses the comma-separated ai.services.engine.urls setting. */
+ public static List parseUrls(String setting) {
+ List urls = new ArrayList<>();
+ if (setting == null) {
+ return urls;
+ }
+ for (String part : setting.split(",")) {
+ String trimmed = part.trim();
+ if (!trimmed.isEmpty()) {
+ urls.add(stripTrailingSlash(trimmed));
+ }
+ }
+ return urls;
+ }
+
+ private static String stripTrailingSlash(String url) {
+ return url.endsWith("/") ? url.substring(0, url.length() - 1) : url;
+ }
+
+ public List getBaseUrls() {
+ return baseUrls;
+ }
+
+ public EngineResponse get(String path, CallerContext caller) {
+ return send("GET", path, caller, null);
+ }
+
+ public EngineResponse post(String path, CallerContext caller, String body) {
+ return send("POST", path, caller, body);
+ }
+
+ public EngineResponse patch(String path, CallerContext caller, String body) {
+ return send("PATCH", path, caller, body);
+ }
+
+ public EngineResponse delete(String path, CallerContext caller) {
+ return send("DELETE", path, caller, null);
+ }
+
+ /**
+ * Try each replica in turn until one answers.
+ *
+ * An answer is final, whatever its status: only an unreachable replica
+ * is worth trying the next one for. A 500 from the engine means the
+ * engine decided something, and repeating a state-changing call
+ * against another replica could apply it twice.
+ */
+ private EngineResponse send(
+ String method, String path, CallerContext caller, String body) {
+ Map headers = caller.asHeaders();
+ EngineException lastFailure = null;
+
+ for (String baseUrl : baseUrls) {
+ try {
+ return transport.send(method, baseUrl + path, headers, body);
+ } catch (EngineException failure) {
+ if (!failure.isUnreachable()) {
+ throw failure;
+ }
+ lastFailure = failure;
+ }
+ }
+
+ throw new EngineException(
+ "no AI Services engine replica answered (tried " + baseUrls.size()
+ + "): " + (lastFailure == null ? "unknown" : lastFailure.getMessage()),
+ lastFailure);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineException.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineException.java
new file mode 100644
index 000000000000..38bb25394b5a
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineException.java
@@ -0,0 +1,61 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+/**
+ * The engine refused a call, or could not be reached.
+ *
+ * Carries the HTTP status and the RFC 9457 problem type where the engine
+ * answered, so a command can map a 403 from the engine onto a CloudStack
+ * permission error rather than a generic failure.
+ */
+public class EngineException extends RuntimeException {
+
+ private static final long serialVersionUID = 1L;
+
+ private final int statusCode;
+ private final String problemType;
+
+ public EngineException(String message) {
+ this(message, 0, null);
+ }
+
+ public EngineException(String message, int statusCode, String problemType) {
+ super(message);
+ this.statusCode = statusCode;
+ this.problemType = problemType;
+ }
+
+ public EngineException(String message, Throwable cause) {
+ super(message, cause);
+ this.statusCode = 0;
+ this.problemType = null;
+ }
+
+ /** HTTP status, or 0 when the engine could not be reached at all. */
+ public int getStatusCode() {
+ return statusCode;
+ }
+
+ /** The RFC 9457 problem type, or null. */
+ public String getProblemType() {
+ return problemType;
+ }
+
+ /** Whether no engine replica answered, as opposed to answering badly. */
+ public boolean isUnreachable() {
+ return statusCode == 0;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJob.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJob.java
new file mode 100644
index 000000000000..4c68e2609dc2
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJob.java
@@ -0,0 +1,114 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/**
+ * One engine async job (SPEC.md section 10).
+ *
+ * The engine deliberately uses CloudStack's own status values — 0
+ * pending, 1 success, 2 failure — so the plugin maps a job onto a
+ * CloudStack async job without translating anything.
+ */
+public class EngineJob {
+
+ public static final int PENDING = 0;
+ public static final int SUCCESS = 1;
+ public static final int FAILURE = 2;
+
+ private final String jobId;
+ private final int status;
+ private final JsonObject result;
+ private final String errorText;
+ private final Integer errorCode;
+
+ EngineJob(String jobId, int status, JsonObject result, String errorText, Integer errorCode) {
+ this.jobId = jobId;
+ this.status = status;
+ this.result = result;
+ this.errorText = errorText;
+ this.errorCode = errorCode;
+ }
+
+ /** Parse a /v1/jobs/{id} body, or the 202 that started it. */
+ public static EngineJob parse(String body) {
+ JsonObject root;
+ try {
+ root = JsonParser.parseString(body).getAsJsonObject();
+ } catch (RuntimeException malformed) {
+ throw new EngineException(
+ "the engine returned an unreadable job document: " + malformed.getMessage());
+ }
+
+ String id = root.has("jobid") && !root.get("jobid").isJsonNull()
+ ? root.get("jobid").getAsString()
+ : null;
+ if (id == null || id.isEmpty()) {
+ throw new EngineException("the engine returned no job id");
+ }
+
+ int status = root.has("jobstatus") ? root.get("jobstatus").getAsInt() : PENDING;
+ JsonObject result = root.has("jobresult") && root.get("jobresult").isJsonObject()
+ ? root.getAsJsonObject("jobresult")
+ : null;
+
+ String errorText = null;
+ Integer errorCode = null;
+ if (status == FAILURE && result != null) {
+ errorText = result.has("errortext") && !result.get("errortext").isJsonNull()
+ ? result.get("errortext").getAsString()
+ : "the engine reported a failure with no detail";
+ if (result.has("errorcode") && !result.get("errorcode").isJsonNull()) {
+ errorCode = result.get("errorcode").getAsInt();
+ }
+ }
+
+ return new EngineJob(id, status, result, errorText, errorCode);
+ }
+
+ public String getJobId() {
+ return jobId;
+ }
+
+ public int getStatus() {
+ return status;
+ }
+
+ public boolean isPending() {
+ return status == PENDING;
+ }
+
+ public boolean isSuccess() {
+ return status == SUCCESS;
+ }
+
+ public boolean isFailure() {
+ return status == FAILURE;
+ }
+
+ public JsonObject getResult() {
+ return result;
+ }
+
+ public String getErrorText() {
+ return errorText;
+ }
+
+ public Integer getErrorCode() {
+ return errorCode;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJobPoller.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJobPoller.java
new file mode 100644
index 000000000000..f0e4e708e739
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineJobPoller.java
@@ -0,0 +1,108 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+/**
+ * Waits for an engine job to finish (SPEC.md section 9).
+ *
+ * "State-changing commands extend BaseAsyncCmd and run as CloudStack
+ * async jobs that poll the engine's /v1/jobs/{id}." This runs inside
+ * that CloudStack job, so blocking here is the intended behaviour: the
+ * caller already has a CloudStack job id to poll.
+ */
+public class EngineJobPoller {
+
+ /** Lets tests run the poll loop without real time passing. */
+ public interface Sleeper {
+ void sleep(long millis) throws InterruptedException;
+ }
+
+ /** Lets tests advance a deadline without real time passing. */
+ public interface Clock {
+ long millis();
+ }
+
+ private static final long DEFAULT_INTERVAL_MILLIS = 2000L;
+
+ private final EngineClient client;
+ private final long intervalMillis;
+ private final long timeoutMillis;
+ private final Sleeper sleeper;
+ private final Clock clock;
+
+ public EngineJobPoller(EngineClient client, long timeoutMillis) {
+ this(client, DEFAULT_INTERVAL_MILLIS, timeoutMillis, Thread::sleep,
+ System::currentTimeMillis);
+ }
+
+ EngineJobPoller(
+ EngineClient client,
+ long intervalMillis,
+ long timeoutMillis,
+ Sleeper sleeper,
+ Clock clock) {
+ this.client = client;
+ this.intervalMillis = intervalMillis;
+ this.timeoutMillis = timeoutMillis;
+ this.sleeper = sleeper;
+ this.clock = clock;
+ }
+
+ /**
+ * Poll until the job leaves the pending state.
+ *
+ * @throws EngineException on failure, timeout, or an unreachable engine.
+ * A timeout is deliberately not a success: the work may still be
+ * running, and reporting it as done would be a lie the operator
+ * acts on.
+ */
+ public EngineJob await(String jobId, CallerContext caller) {
+ long deadline = clock.millis() + timeoutMillis;
+
+ while (true) {
+ EngineResponse answer = client.get("/v1/jobs/" + jobId, caller);
+ if (!answer.isSuccess()) {
+ throw new EngineException(
+ "could not read engine job " + jobId + ": HTTP "
+ + answer.getStatusCode(),
+ answer.getStatusCode(), null);
+ }
+
+ EngineJob job = EngineJob.parse(answer.getBody());
+ if (job.isFailure()) {
+ throw new EngineException(
+ job.getErrorText(),
+ job.getErrorCode() == null ? 0 : job.getErrorCode(),
+ null);
+ }
+ if (!job.isPending()) {
+ return job;
+ }
+
+ if (clock.millis() >= deadline) {
+ throw new EngineException(
+ "engine job " + jobId + " did not finish within "
+ + (timeoutMillis / 1000) + "s; it may still be running");
+ }
+
+ try {
+ sleeper.sleep(intervalMillis);
+ } catch (InterruptedException interrupted) {
+ Thread.currentThread().interrupt();
+ throw new EngineException("interrupted waiting for engine job " + jobId);
+ }
+ }
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EnginePaths.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EnginePaths.java
new file mode 100644
index 000000000000..d3e014f4ac24
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EnginePaths.java
@@ -0,0 +1,39 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+
+/** Building engine request paths, shared by the sync and async bases. */
+public final class EnginePaths {
+
+ private EnginePaths() {
+ }
+
+ /**
+ * Append a query parameter, choosing ? or & as needed.
+ *
+ * Values are URL-encoded: a model name or Hugging Face repo id
+ * contains slashes and dots that would otherwise change the path.
+ */
+ public static String withQuery(String path, String name, Object value) {
+ if (value == null) {
+ return path;
+ }
+ return path + (path.contains("?") ? '&' : '?') + name + "="
+ + URLEncoder.encode(String.valueOf(value), StandardCharsets.UTF_8);
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineResponse.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineResponse.java
new file mode 100644
index 000000000000..adb182c3dd9c
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineResponse.java
@@ -0,0 +1,84 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/** What an engine replica answered. */
+public class EngineResponse {
+
+ private final int statusCode;
+ private final String body;
+
+ public EngineResponse(int statusCode, String body) {
+ this.statusCode = statusCode;
+ this.body = body == null ? "" : body;
+ }
+
+ public int getStatusCode() {
+ return statusCode;
+ }
+
+ public String getBody() {
+ return body;
+ }
+
+ public boolean isSuccess() {
+ return statusCode >= 200 && statusCode < 300;
+ }
+
+ /** True for an async command's 202, which carries a job id to poll. */
+ public boolean isAccepted() {
+ return statusCode == 202;
+ }
+
+ /**
+ * The engine's own account of a failure, ready to append, or "".
+ *
+ *
The engine answers in RFC 9457 problem JSON so that its
+ * caller can say why something failed, and this plugin is its
+ * only caller. Both the sync and the async path reported a bare
+ * status until a live round trip showed what that costs: a
+ * capacity call said "returned 503 for /v1/capacity" while the
+ * body said "capacity has not been observed yet", and a refused
+ * batch said "HTTP 400" while the body named the field.
+ *
+ *
It is appended to the status rather than replacing it,
+ * because the status is what gets grepped for, and a body that is
+ * not problem JSON yields nothing: a proxy or load balancer may
+ * have answered, and a parse failure must not displace the real
+ * one.
+ */
+ public String explain() {
+ if (body.trim().isEmpty()) {
+ return "";
+ }
+ try {
+ JsonObject problem = JsonParser.parseString(body).getAsJsonObject();
+ for (String field : new String[] {"detail", "title"}) {
+ if (problem.has(field) && problem.get(field).isJsonPrimitive()) {
+ String said = problem.get(field).getAsString().trim();
+ if (!said.isEmpty()) {
+ return ": " + said;
+ }
+ }
+ }
+ } catch (RuntimeException notProblemJson) {
+ return "";
+ }
+ return "";
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineTransport.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineTransport.java
new file mode 100644
index 000000000000..f179aacfbe71
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/EngineTransport.java
@@ -0,0 +1,32 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.util.Map;
+
+/**
+ * One HTTP exchange with an engine replica.
+ *
+ * Separated from {@link EngineClient} so failover and caller-context
+ * handling can be tested without a socket or a certificate.
+ */
+public interface EngineTransport {
+
+ /**
+ * @throws EngineException with status 0 when the replica cannot be
+ * reached, which is the only case the client fails over on.
+ */
+ EngineResponse send(String method, String url, Map headers, String body);
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/HttpEngineTransport.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/HttpEngineTransport.java
new file mode 100644
index 000000000000..ed97eff8a259
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/HttpEngineTransport.java
@@ -0,0 +1,107 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.Map;
+
+/**
+ * The mTLS transport to the engine (SPEC.md section 11).
+ *
+ * The engine trusts the caller context this plugin asserts, so the client
+ * certificate is what earns that trust. A missing certificate is a
+ * configuration error rather than a reason to fall back to plain TLS:
+ * falling back would let anything that can reach the engine claim to be
+ * any tenant.
+ */
+public class HttpEngineTransport implements EngineTransport {
+
+ private final HttpClient client;
+ private final Duration timeout;
+
+ public HttpEngineTransport(
+ Integer timeoutSeconds,
+ String clientCert,
+ String clientKey,
+ String trustStore,
+ String trustStorePassword) {
+ this.timeout = Duration.ofSeconds(timeoutSeconds == null ? 30 : timeoutSeconds);
+ this.client = HttpClient.newBuilder()
+ .connectTimeout(this.timeout)
+ .sslContext(MutualTls.contextFor(
+ clientCert, clientKey, trustStore, trustStorePassword))
+ .build();
+ }
+
+ /** For tests, which supply their own client. */
+ HttpEngineTransport(HttpClient client, Duration timeout) {
+ this.client = client;
+ this.timeout = timeout;
+ }
+
+ @Override
+ public EngineResponse send(
+ String method, String url, Map headers, String body) {
+ HttpRequest.BodyPublisher publisher = body == null
+ ? HttpRequest.BodyPublishers.noBody()
+ : HttpRequest.BodyPublishers.ofString(body);
+
+ HttpRequest.Builder request = HttpRequest.newBuilder()
+ .uri(URI.create(url))
+ .timeout(timeout)
+ .method(method, publisher);
+ for (Map.Entry header : headers.entrySet()) {
+ request.header(header.getKey(), header.getValue());
+ }
+ if (body != null) {
+ request.header("Content-Type", "application/json");
+ }
+
+ try {
+ HttpResponse response =
+ client.send(request.build(), HttpResponse.BodyHandlers.ofString());
+ return new EngineResponse(response.statusCode(), response.body());
+ } catch (IOException problem) {
+ // Status 0: unreachable, so EngineClient tries the next replica.
+ throw new EngineException(
+ "could not reach engine at " + url + ": " + describe(problem), problem);
+ } catch (InterruptedException interrupted) {
+ Thread.currentThread().interrupt();
+ throw new EngineException("interrupted calling engine at " + url, interrupted);
+ }
+ }
+
+ /**
+ * What to tell an operator about a failure that may say nothing.
+ *
+ * The IOException behind a refused connection can carry no
+ * message, and an operator who killed both replicas was told
+ * "could not reach engine at https://…/v1/models: null". The
+ * class name is not much, but it is a fact about what happened,
+ * and the cause is attached to the exception either way.
+ */
+ static String describe(Exception problem) {
+ String said = problem.getMessage();
+ if (said == null || said.trim().isEmpty()) {
+ return problem.getClass().getSimpleName();
+ }
+ return said;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/MutualTls.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/MutualTls.java
new file mode 100644
index 000000000000..4a8b40313f1e
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/engine/MutualTls.java
@@ -0,0 +1,125 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import java.io.FileInputStream;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.security.KeyStore;
+import java.security.SecureRandom;
+
+import javax.net.ssl.KeyManagerFactory;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManagerFactory;
+
+/** Builds the SSLContext the plugin presents to the engine. */
+public final class MutualTls {
+
+ private MutualTls() {
+ }
+
+ /**
+ * @throws EngineException when mTLS is not fully configured. Refusing
+ * to start beats quietly connecting without a client
+ * certificate, which would let the engine trust an
+ * unauthenticated caller's asserted identity.
+ */
+ public static SSLContext contextFor(
+ String keyStorePath,
+ String keyStorePassword,
+ String trustStorePath,
+ String trustStorePassword) {
+ requireConfigured(keyStorePath, "ai.services.engine.tls.client.cert");
+ requireConfigured(trustStorePath, "ai.services.engine.tls.truststore");
+
+ try {
+ KeyStore keyStore = load(keyStorePath, keyStorePassword);
+ KeyManagerFactory keyManagers =
+ KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
+ keyManagers.init(keyStore, charsOf(keyStorePassword));
+
+ // The truststore needs its own password. It was read with
+ // an empty one, which no operator could produce: keytool
+ // refuses a password under six characters, and a PKCS12
+ // store openssl writes with an empty password loads as
+ // *zero entries* rather than failing.
+ KeyStore trustStore = load(trustStorePath, trustStorePassword);
+ if (trustStore.size() == 0) {
+ // TrustManagerFactory would accept this and build a
+ // trust manager that trusts nothing, so every call
+ // would fail at the handshake with an error naming
+ // neither the truststore nor the CA.
+ throw new EngineException(
+ "the trust store at " + trustStorePath + " holds no certificates, "
+ + "so the plugin would trust no engine. Import the engine's "
+ + "CA into it: keytool -importcert -alias aisvc-ca -file "
+ + "ca.pem -keystore " + trustStorePath + " -storetype PKCS12");
+ }
+ TrustManagerFactory trustManagers =
+ TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
+ trustManagers.init(trustStore);
+
+ SSLContext context = SSLContext.getInstance("TLSv1.3");
+ context.init(
+ keyManagers.getKeyManagers(),
+ trustManagers.getTrustManagers(),
+ new SecureRandom());
+ return context;
+ } catch (EngineException passthrough) {
+ throw passthrough;
+ } catch (Exception failure) {
+ String hint = "";
+ String message = failure.getMessage() == null ? "" : failure.getMessage();
+ // JDK 17 reports a wrong store password two different ways
+ // depending on where it notices — "keystore password was
+ // incorrect" and "Integrity check failed" — and neither
+ // says which of the two stores it was reading.
+ if (message.contains("password was incorrect")
+ || message.contains("Integrity check failed")) {
+ // The likeliest cause by a distance, and the raw
+ // message does not say which of the two stores it was.
+ hint = " — check ai.services.engine.tls.client.key and "
+ + "ai.services.engine.tls.truststore.password";
+ }
+ throw new EngineException(
+ "could not build the mTLS context for the AI Services engine: "
+ + failure.getMessage() + hint,
+ failure);
+ }
+ }
+
+ private static void requireConfigured(String value, String setting) {
+ if (value == null || value.trim().isEmpty()) {
+ throw new EngineException(
+ "mTLS is required to call the AI Services engine; set " + setting);
+ }
+ if (!Files.isReadable(Paths.get(value))) {
+ throw new EngineException(setting + " points at an unreadable file: " + value);
+ }
+ }
+
+ private static KeyStore load(String path, String password) throws Exception {
+ KeyStore store = KeyStore.getInstance(KeyStore.getDefaultType());
+ try (InputStream in = new FileInputStream(path)) {
+ store.load(in, charsOf(password));
+ }
+ return store;
+ }
+
+ private static char[] charsOf(String password) {
+ return password == null ? new char[0] : password.toCharArray();
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListener.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListener.java
new file mode 100644
index 000000000000..719316dd970c
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListener.java
@@ -0,0 +1,133 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.maintenance;
+
+import java.util.UUID;
+import java.util.function.Function;
+
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.framework.events.Event;
+import org.apache.cloudstack.framework.events.EventBus;
+import org.apache.cloudstack.framework.events.EventBusException;
+import org.apache.cloudstack.framework.events.EventSubscriber;
+import org.apache.cloudstack.framework.events.EventTopic;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * Hears about host maintenance and drains GPU nodes first (SPEC.md section 7).
+ *
+ *
This is the best hook CloudStack 4.23 offers, and it is not a good
+ * one. There is no synchronous pre-maintenance extension point:
+ * {@code ResourceStateAdapter} covers host creation and deletion,
+ * the agent {@code Listener} covers connect, disconnect and removal, and
+ * {@code ResourceState} is driven by the older {@code StateMachine}, which
+ * accepts no listeners. The event bus is what is left, and it is
+ * asynchronous — the host has already begun its transition by the time
+ * this runs — and no event bus plugin is enabled in a default install.
+ *
+ *
So this subscribes where it can, and where it cannot it says so
+ * loudly at startup rather than leaving an operator believing that drains
+ * happen on their own. Either way {@code drainAiNode} remains the
+ * dependable path, and the UI's maintenance screen should say so.
+ */
+public class AiMaintenanceListener implements EventSubscriber {
+
+ private static final Logger LOG = LogManager.getLogger(AiMaintenanceListener.class);
+
+ /** CloudStack's {@code EventTypes.EVENT_MAINTENANCE_PREPARE}. */
+ public static final String MAINTENANCE_EVENT = "MAINT.PREPARE";
+
+ /** The resource type CloudStack tags host maintenance events with. */
+ public static final String HOST_CATEGORY = "Host";
+
+ private final MaintenanceDrain drain;
+ private final Function resolveHostId;
+ private UUID subscriptionId;
+ private String inactiveReason = "";
+
+ public AiMaintenanceListener(MaintenanceDrain drain, Function resolveHostId) {
+ this.drain = drain;
+ this.resolveHostId = resolveHostId;
+ }
+
+ /** The one topic this listens on: host maintenance, nothing else. */
+ public static EventTopic topic() {
+ return new EventTopic("ActionEvent", MAINTENANCE_EVENT, HOST_CATEGORY, null, null);
+ }
+
+ /**
+ * Subscribe to the bus, if there is one.
+ *
+ * @return true when automatic draining is live; false when it is not,
+ * in which case {@link #inactiveReason()} says why and what to
+ * do instead.
+ */
+ public boolean subscribe(EventBus bus) {
+ if (bus == null) {
+ inactiveReason = "no event bus is configured, so host maintenance will not "
+ + "drain GPU nodes automatically; enable an event bus plugin, or run "
+ + "drainAiNode on each GPU node before putting its host into maintenance";
+ LOG.warn("AI Services: {}", inactiveReason);
+ return false;
+ }
+
+ try {
+ subscriptionId = UUID.randomUUID();
+ bus.subscribe(topic(), this);
+ LOG.info("AI Services: listening for host maintenance to drain GPU nodes");
+ return true;
+ } catch (EventBusException e) {
+ inactiveReason = "could not subscribe to the event bus (" + e.getMessage()
+ + "), so host maintenance will not drain GPU nodes automatically; "
+ + "run drainAiNode on each GPU node before putting its host into maintenance";
+ LOG.warn("AI Services: {}", inactiveReason);
+ subscriptionId = null;
+ return false;
+ }
+ }
+
+ public boolean isActive() {
+ return subscriptionId != null;
+ }
+
+ public String inactiveReason() {
+ return inactiveReason;
+ }
+
+ @Override
+ public void onEvent(Event event) {
+ if (event == null
+ || !MAINTENANCE_EVENT.equals(event.getEventType())
+ || !HOST_CATEGORY.equals(event.getResourceType())) {
+ return;
+ }
+
+ try {
+ Long hostId = resolveHostId.apply(event.getResourceUUID());
+ if (hostId == null) {
+ LOG.debug("Ignoring maintenance for unknown host {}", event.getResourceUUID());
+ return;
+ }
+ drain.beforeMaintenance(hostId, CallerContext.system());
+ } catch (RuntimeException e) {
+ // Never throw back at the bus: an exception here can
+ // unsubscribe this listener or stall other subscribers, and
+ // then nothing drains for the rest of the uptime.
+ LOG.error("Failed to drain GPU nodes for host {} before maintenance",
+ event.getResourceUUID(), e);
+ }
+ }
+}
diff --git a/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrain.java b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrain.java
new file mode 100644
index 000000000000..0165e1125c96
--- /dev/null
+++ b/plugins/api/ai-services/src/main/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrain.java
@@ -0,0 +1,119 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.maintenance;
+
+import java.util.List;
+
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * Drains GPU nodes off a host before it enters maintenance (SPEC.md section 7).
+ *
+ *
This exists because passthrough GPUs cannot live-migrate (ADR-0003).
+ * CloudStack's own maintenance moves VMs off a host; these VMs cannot be
+ * moved, so they have to be destroyed and replaced elsewhere first.
+ * Without that, maintenance stalls on VMs nothing can migrate.
+ *
+ *
The decision is the engine's, not this class's: whether there is
+ * capacity elsewhere and whether a force is needed lives in the engine's
+ * {@code lifecycle} module, and is not reimplemented here. All this does
+ * is ask, once per node, and report what came back.
+ *
+ *
On when this runs. CloudStack 4.23 has no synchronous
+ * pre-maintenance extension point: {@code ResourceStateAdapter} covers
+ * host create and delete only, the agent {@code Listener} covers connect,
+ * disconnect and removal, and {@code ResourceState}'s state machine is the
+ * older {@code StateMachine}, which takes no listeners. The only hook is
+ * the event bus, which is not enabled in a default install. So
+ * {@link AiMaintenanceListener} wires this where it can and says plainly
+ * at startup when it cannot.
+ */
+public class MaintenanceDrain {
+
+ private static final Logger LOG = LogManager.getLogger(MaintenanceDrain.class);
+
+ /** What the engine said about one node. */
+ public enum Outcome {
+ /** The node is gone and its replicas are elsewhere. */
+ DRAINED,
+ /** Capacity elsewhere is short; an admin must confirm a forced drain. */
+ NEEDS_FORCE,
+ /** The drain did not finish inside the configured timeout. */
+ TIMED_OUT,
+ }
+
+ /** Finds the GPU node VMs running on a host. */
+ public interface NodeLookup {
+ List nodesOnHost(long hostId);
+ }
+
+ /** Asks the engine to drain one node. */
+ public interface Drainer {
+ Outcome drain(String nodeId, CallerContext caller, int timeoutSeconds);
+ }
+
+ /** Tells the operator when maintenance needs a decision from them. */
+ public interface Alerts {
+ void needsForcedDrain(long hostId, String nodeId, String reason);
+ }
+
+ private final NodeLookup lookup;
+ private final Drainer drainer;
+ private final Alerts alerts;
+ private final int timeoutSeconds;
+
+ public MaintenanceDrain(NodeLookup lookup, Drainer drainer, Alerts alerts, int timeoutSeconds) {
+ this.lookup = lookup;
+ this.drainer = drainer;
+ this.alerts = alerts;
+ this.timeoutSeconds = timeoutSeconds;
+ }
+
+ /**
+ * Drain every GPU node on this host.
+ *
+ * @return true when maintenance may proceed; false when something needs
+ * an operator's decision first.
+ */
+ public boolean beforeMaintenance(long hostId, CallerContext caller) {
+ List nodes = lookup.nodesOnHost(hostId);
+ if (nodes.isEmpty()) {
+ return true;
+ }
+
+ LOG.info("Draining {} GPU node(s) from host {} before maintenance", nodes.size(), hostId);
+
+ // Every node is attempted even after one fails. Stopping early
+ // would leave the rest serving on a host that is going down
+ // regardless, and the operator wants one list of problems.
+ boolean mayProceed = true;
+ for (String nodeId : nodes) {
+ Outcome outcome = drainer.drain(nodeId, caller, timeoutSeconds);
+ if (outcome == Outcome.DRAINED) {
+ continue;
+ }
+
+ mayProceed = false;
+ String reason = outcome == Outcome.NEEDS_FORCE
+ ? "not enough GPU capacity elsewhere for this node's replicas"
+ : "the drain did not finish within " + timeoutSeconds + " seconds";
+ LOG.warn("Host {} cannot enter maintenance yet: {} ({})", hostId, nodeId, reason);
+ alerts.needsForcedDrain(hostId, nodeId, reason);
+ }
+ return mayProceed;
+ }
+}
diff --git a/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/module.properties b/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/module.properties
new file mode 100644
index 000000000000..2f566c53dc22
--- /dev/null
+++ b/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/module.properties
@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with this
+# work for additional information regarding copyright ownership. The ASF
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+name=ai-services
+parent=api
diff --git a/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/spring-ai-services-context.xml b/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/spring-ai-services-context.xml
new file mode 100644
index 000000000000..6c4b2d94c991
--- /dev/null
+++ b/plugins/api/ai-services/src/main/resources/META-INF/cloudstack/ai-services/spring-ai-services-context.xml
@@ -0,0 +1,34 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/plugins/api/ai-services/src/main/resources/META-INF/db/schema-ai-services.sql b/plugins/api/ai-services/src/main/resources/META-INF/db/schema-ai-services.sql
new file mode 100644
index 000000000000..6a7cd68dd02b
--- /dev/null
+++ b/plugins/api/ai-services/src/main/resources/META-INF/db/schema-ai-services.sql
@@ -0,0 +1,50 @@
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with this
+-- work for additional information regarding copyright ownership. The ASF
+-- licenses this file to you under the Apache License, Version 2.0 (the
+-- "License"); you may not use this file except in compliance with the
+-- License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+-- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+-- License for the specific language governing permissions and limitations
+-- under the License.
+
+--
+-- AI Services ownership table (SPEC.md section 9).
+--
+-- Deliberately minimal. The engine is the source of truth for runtime
+-- state: replicas, health, rollouts and usage all live there. This table
+-- exists only so CloudStack can do what CloudStack does natively --
+-- enforce ownership, filter list commands by account and domain, and
+-- clean up when an account or domain is deleted. Duplicating engine
+-- state here would create two answers to the same question.
+--
+
+CREATE TABLE IF NOT EXISTS `cloud`.`ai_deployment` (
+ `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+ `uuid` varchar(40) NOT NULL COMMENT 'UUID exposed through the API',
+ `name` varchar(255) NOT NULL COMMENT 'catalog name of the deployed model',
+ `account_id` bigint unsigned NOT NULL COMMENT 'owning account',
+ `domain_id` bigint unsigned NOT NULL COMMENT 'owning domain',
+ `zone_id` bigint unsigned NOT NULL COMMENT 'data center the deployment runs in',
+ `engine_id` varchar(255) NOT NULL COMMENT 'the engine''s identifier for this deployment',
+ `state` varchar(32) NOT NULL DEFAULT 'Allocated' COMMENT 'last state the engine reported',
+ `created` datetime NOT NULL,
+ `removed` datetime DEFAULT NULL COMMENT 'soft delete, as CloudStack expects',
+ PRIMARY KEY (`id`),
+ UNIQUE KEY `uc_ai_deployment__uuid` (`uuid`),
+ KEY `i_ai_deployment__account_id` (`account_id`),
+ KEY `i_ai_deployment__domain_id` (`domain_id`),
+ KEY `i_ai_deployment__zone_id` (`zone_id`),
+ KEY `i_ai_deployment__removed` (`removed`),
+ CONSTRAINT `fk_ai_deployment__account_id`
+ FOREIGN KEY (`account_id`) REFERENCES `account` (`id`) ON DELETE CASCADE,
+ CONSTRAINT `fk_ai_deployment__domain_id`
+ FOREIGN KEY (`domain_id`) REFERENCES `domain` (`id`) ON DELETE CASCADE,
+ CONSTRAINT `fk_ai_deployment__zone_id`
+ FOREIGN KEY (`zone_id`) REFERENCES `data_center` (`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesCatalogueTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesCatalogueTest.java
new file mode 100644
index 000000000000..ad19d96a7b98
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesCatalogueTest.java
@@ -0,0 +1,139 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import org.apache.cloudstack.ai.dao.AiDeploymentVO;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+/** Events, usage types and the ownership row (SPEC.md section 9). */
+class AiServicesCatalogueTest {
+
+ @Test
+ void everyEventTheSpecNamesExists() {
+ Set events = new HashSet<>(java.util.Arrays.asList(AiServicesEvents.all()));
+
+ for (String expected : new String[] {
+ "AI.MODEL.MIRROR", "AI.MODEL.PUBLISH", "AI.MODEL.DEPLOY",
+ "AI.MODEL.UPDATE", "AI.MODEL.DELETE", "AI.ROLLOUT.PROMOTE",
+ "AI.ROLLOUT.ROLLBACK", "AI.PROFILE.UPDATE", "AI.KEY.CREATE",
+ "AI.KEY.REVOKE", "AI.BUDGET.THRESHOLD", "AI.NODE.DRAIN",
+ "AI.GUARDRAIL.BLOCK"}) {
+ assertTrue(events.contains(expected), "missing event " + expected);
+ }
+ }
+
+ @Test
+ void eventsFollowCloudStacksDottedConvention() {
+ for (String event : AiServicesEvents.all()) {
+ assertTrue(event.startsWith("AI."), event);
+ assertEquals(event.toUpperCase(java.util.Locale.ROOT), event);
+ }
+ }
+
+ @Test
+ void eventNamesAreUnique() {
+ Set seen = new HashSet<>();
+ for (String event : AiServicesEvents.all()) {
+ assertTrue(seen.add(event), "duplicate event " + event);
+ }
+ }
+
+ @Test
+ void usageTypesSitAboveCloudStacksOwnRange() {
+ // CloudStack's built-in usage types stop well below 100, so a
+ // provider's billing pipeline can tell ours apart unambiguously.
+ for (int type : AiServicesUsageTypes.all()) {
+ assertTrue(type >= 100, "usage type " + type + " could collide");
+ }
+ }
+
+ @ParameterizedTest
+ @ValueSource(ints = {100, 101, 102, 103, 104})
+ void everyUsageTypeDescribesItself(int type) {
+ assertTrue(AiServicesUsageTypes.describe(type).startsWith("AI "));
+ }
+
+ @Test
+ void anUnknownUsageTypeIsRejected() {
+ assertThrows(IllegalArgumentException.class, () -> AiServicesUsageTypes.describe(7));
+ }
+
+ @Test
+ void theSpecsFourBillableThingsAreCovered() {
+ // Tokens, GPU hours, adapter premium and batch tokens.
+ assertEquals(5, AiServicesUsageTypes.all().length);
+ }
+
+ @Test
+ void anOwnershipRowCarriesItsOwner() {
+ AiDeploymentVO row = new AiDeploymentVO("llama", 5L, 2L, 1L, "eng-1");
+
+ assertEquals("llama", row.getName());
+ assertEquals(5L, row.getAccountId());
+ assertEquals(2L, row.getDomainId());
+ assertEquals(1L, row.getZoneId());
+ assertEquals("eng-1", row.getEngineId());
+ }
+
+ @Test
+ void anOwnershipRowGetsAUuidAndACreationTime() {
+ AiDeploymentVO row = new AiDeploymentVO("m", 1L, 1L, 1L, "e");
+
+ assertNotNull(row.getUuid());
+ assertEquals(36, row.getUuid().length());
+ assertNotNull(row.getCreated());
+ }
+
+ @Test
+ void aNewRowStartsAllocatedAndNotRemoved() {
+ AiDeploymentVO row = new AiDeploymentVO("m", 1L, 1L, 1L, "e");
+
+ assertEquals("Allocated", row.getState());
+ assertEquals(null, row.getRemoved());
+ }
+
+ @Test
+ void theStateTracksWhatTheEngineReports() {
+ AiDeploymentVO row = new AiDeploymentVO("m", 1L, 1L, 1L, "e");
+
+ row.setState("Running");
+
+ assertEquals("Running", row.getState());
+ }
+
+ @Test
+ void twoRowsGetDifferentUuids() {
+ assertTrue(!new AiDeploymentVO("m", 1L, 1L, 1L, "e").getUuid()
+ .equals(new AiDeploymentVO("m", 1L, 1L, 1L, "e").getUuid()));
+ }
+
+ @Test
+ void aRowPrintsReadablyForLogs() {
+ String printed = new AiDeploymentVO("llama", 5L, 2L, 1L, "e").toString();
+
+ assertTrue(printed.contains("llama"));
+ assertTrue(printed.contains("account=5"));
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesConfigTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesConfigTest.java
new file mode 100644
index 000000000000..76e70836dd20
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesConfigTest.java
@@ -0,0 +1,151 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+import org.apache.cloudstack.framework.config.ConfigKey;
+import org.junit.jupiter.api.Test;
+
+/**
+ * The plugin's settings (SPEC.md section 9).
+ *
+ * Scope is the thing worth asserting: a setting at the wrong scope either
+ * cannot be varied where it must be, or can be varied where it must not.
+ */
+class AiServicesConfigTest {
+
+ @Test
+ void everyKeyIsExported() {
+ assertEquals(10, AiServicesConfig.all().length);
+ }
+
+ @Test
+ void keyNamesAreNamespaced() {
+ for (ConfigKey> key : AiServicesConfig.all()) {
+ assertTrue(key.key().startsWith("ai.services."),
+ key.key() + " should be under the ai.services namespace");
+ }
+ }
+
+ @Test
+ void keyNamesAreUnique() {
+ Set names = new HashSet<>();
+ for (ConfigKey> key : AiServicesConfig.all()) {
+ assertTrue(names.add(key.key()), "duplicate config key " + key.key());
+ }
+ }
+
+ @Test
+ void enablementIsPerZone() {
+ // A provider may run GPU capacity in one zone only.
+ assertEquals(
+ java.util.Collections.singletonList(ConfigKey.Scope.Zone),
+ AiServicesConfig.Enabled.getScopes());
+ }
+
+ @Test
+ void hubApprovalIsPerDomain() {
+ // Section 5 lets one reseller mirror directly while others request it.
+ assertEquals(
+ java.util.Collections.singletonList(ConfigKey.Scope.Domain),
+ AiServicesConfig.HfRequireApproval.getScopes());
+ }
+
+ @Test
+ void engineSettingsAreGlobal() {
+ for (ConfigKey> key : Arrays.asList(
+ AiServicesConfig.EngineUrls,
+ AiServicesConfig.EngineTimeout,
+ AiServicesConfig.EngineClientCert,
+ AiServicesConfig.EngineClientKey,
+ AiServicesConfig.EngineTrustStore)) {
+ assertEquals(
+ java.util.Collections.singletonList(ConfigKey.Scope.Global),
+ key.getScopes(), key.key());
+ }
+ }
+
+ @Test
+ void theDefaultIsDisabled() {
+ // Enabling a zone should be a decision, not what happens on upgrade.
+ assertFalse(Boolean.parseBoolean(AiServicesConfig.Enabled.defaultValue()));
+ }
+
+ @Test
+ void hubApprovalDefaultsToRequired() {
+ assertTrue(Boolean.parseBoolean(AiServicesConfig.HfRequireApproval.defaultValue()));
+ }
+
+ @Test
+ void thereIsNoDefaultEngineUrl() {
+ // A default would point the plugin somewhere nobody chose.
+ assertEquals("", AiServicesConfig.EngineUrls.defaultValue());
+ }
+
+ @Test
+ void theDrainTimeoutMatchesTheSpecDefault() {
+ // SPEC.md section 7: 15 minutes.
+ assertEquals("900", AiServicesConfig.MaintenanceDrainTimeout.defaultValue());
+ }
+
+ @Test
+ void everyKeyIsDynamic() {
+ // None of these should need a management server restart.
+ for (ConfigKey> key : AiServicesConfig.all()) {
+ assertTrue(key.isDynamic(), key.key() + " should be dynamic");
+ }
+ }
+
+ @Test
+ void everyKeyDocumentsItself() {
+ for (ConfigKey> key : AiServicesConfig.all()) {
+ assertTrue(key.description() != null && key.description().length() > 20,
+ key.key() + " needs a usable description");
+ }
+ }
+
+ /**
+ * A password must sit in a category CloudStack encrypts.
+ *
+ *
{@code ConfigurationVO.isEncrypted()} returns true only for the
+ * categories "Hidden" and "Secure" — verified against the bytecode
+ * of cloud-framework-config, where it is a literal
+ * {@code StringUtils.equalsAny(getCategory(), "Hidden", "Secure")}.
+ * Anything else is stored in the database, and returned by
+ * {@code listConfigurations}, in cleartext.
+ *
+ *
The trust store's password is deliberately not here: a trust
+ * store holds public certificates, so its password protects
+ * nothing and Java's own convention is the well-known "changeit".
+ */
+ @Test
+ void theKeyStorePasswordSitsInAnEncryptedCategory() {
+ assertEquals("Secure", AiServicesConfig.EngineClientKey.category());
+ }
+
+ @Test
+ void theOtherKeysStayWhereAnOperatorLooksForThem() {
+ assertEquals("Advanced", AiServicesConfig.EngineClientCert.category());
+ assertEquals("Advanced", AiServicesConfig.EngineTrustStore.category());
+ assertEquals("Advanced", AiServicesConfig.EngineUrls.category());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesManagerImplTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesManagerImplTest.java
new file mode 100644
index 000000000000..0f61ff242cd5
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesManagerImplTest.java
@@ -0,0 +1,162 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+
+import org.apache.cloudstack.ai.api.command.ListAiModelsCmd;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.BaseCmd;
+import org.apache.cloudstack.framework.config.ConfigKey;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.apache.cloudstack.ai.dao.AiDeploymentDao;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import com.cloud.domain.DomainVO;
+import com.cloud.domain.dao.DomainDao;
+
+import com.cloud.utils.component.PluggableService;
+
+/**
+ * Command and configuration registration (SPEC.md section 9).
+ *
+ * CloudStack discovers what a plugin offers through
+ * {@link PluggableService#getCommands()} and {@code Configurable}. A
+ * command missing from that list is simply not an API, however complete
+ * the class is, so the registration is worth asserting.
+ */
+class AiServicesManagerImplTest {
+
+ private AiServicesManagerImpl manager;
+
+ @BeforeEach
+ void setUp() {
+ manager = new AiServicesManagerImpl();
+ }
+
+ @Test
+ void itIsAPluggableService() {
+ assertTrue(manager instanceof PluggableService);
+ }
+
+ @Test
+ void itRegistersItsCommands() {
+ List> commands = manager.getCommands();
+
+ assertFalse(commands.isEmpty());
+ assertTrue(commands.contains(ListAiModelsCmd.class));
+ }
+
+ @Test
+ void everyRegisteredCommandIsAnApiCommand() {
+ for (Class> command : manager.getCommands()) {
+ assertNotNull(command.getAnnotation(APICommand.class),
+ command.getSimpleName() + " is registered but has no @APICommand");
+ assertTrue(BaseCmd.class.isAssignableFrom(command),
+ command.getSimpleName() + " does not extend BaseCmd");
+ }
+ }
+
+ @Test
+ void registeredCommandsAreDistinct() {
+ List> commands = manager.getCommands();
+
+ assertEquals(commands.size(), new java.util.HashSet<>(commands).size());
+ }
+
+ @Test
+ void itNamesItselfAsTheConfigComponent() {
+ assertEquals("AiServicesManagerImpl", manager.getConfigComponentName());
+ }
+
+ @Test
+ void itExportsEveryConfigKey() {
+ ConfigKey>[] keys = manager.getConfigKeys();
+
+ assertEquals(AiServicesConfig.all().length, keys.length);
+ }
+
+ @Test
+ void theDomainPathIsResolvedFromTheDomainDao() {
+ // The engine decides domain-admin visibility by prefix-matching
+ // this, so a partial path hides or leaks a whole domain.
+ DomainDao domains = mock(DomainDao.class);
+ DomainVO domain = new DomainVO("Acme", 2L, 1L, "Acme");
+ domain.setPath("/Customers/Acme/");
+ when(domains.findById(7L)).thenReturn(domain);
+ manager.setDomainDao(domains);
+
+ assertEquals("/Customers/Acme", manager.domainPathOf(7L));
+ }
+
+ @Test
+ void theRootDomainPathStaysASingleSlash() {
+ DomainDao domains = mock(DomainDao.class);
+ DomainVO root = new DomainVO("ROOT", 1L, null, "ROOT");
+ root.setPath("/");
+ when(domains.findById(1L)).thenReturn(root);
+ manager.setDomainDao(domains);
+
+ assertEquals("/", manager.domainPathOf(1L));
+ }
+
+ @Test
+ void anUnknownDomainRefusesRatherThanGuessing() {
+ // Calling the engine with a made-up domain would widen or hide
+ // access silently.
+ DomainDao domains = mock(DomainDao.class);
+ when(domains.findById(anyLong())).thenReturn(null);
+ manager.setDomainDao(domains);
+
+ IllegalStateException failure = assertThrows(
+ IllegalStateException.class, () -> manager.domainPathOf(99L));
+
+ assertTrue(failure.getMessage().contains("refusing"));
+ }
+
+ @Test
+ void cleanupRemovesTheAccountsOwnershipRows() {
+ AiDeploymentDao deployments = mock(AiDeploymentDao.class);
+ when(deployments.removeByAccount(5L)).thenReturn(3);
+ manager.setDeploymentDao(deployments);
+
+ assertEquals(3, manager.cleanupAccount(5L));
+ verify(deployments).removeByAccount(5L);
+ }
+
+ @Test
+ void cleanupIsSafeBeforeTheDaoIsInjected() {
+ assertEquals(0, manager.cleanupAccount(5L));
+ }
+
+ @Test
+ void aTransportCanBeInjectedWithoutTouchingConfiguration() {
+ // Lets a test drive the manager without an mTLS keystore; building
+ // the client itself needs the config framework, so that is covered
+ // by EngineClientTest rather than here.
+ manager.setTransport((method, url, headers, body) -> null);
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesSchemaTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesSchemaTest.java
new file mode 100644
index 000000000000..8cd8e5f4daae
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/AiServicesSchemaTest.java
@@ -0,0 +1,215 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Applying the plugin's own table (SPEC.md section 9).
+ *
+ *
`ai_deployment` was shipped as a .sql file on the classpath with
+ * nothing to run it. CloudStack applies schema through `DbUpgrade`
+ * classes registered in its core upgrade chain, and the precedent for a
+ * plugin's tables — Quota — is that they live in CloudStack's own
+ * `engine/schema` scripts. Neither is available to a plugin dropped
+ * into an existing management server, so the table was never created
+ * and the first deployAiModel would have failed on a missing table.
+ *
+ *
So the plugin applies it itself, at startup, idempotently. The
+ * statements are `IF NOT EXISTS`, so a management server that already
+ * has the table does nothing and one that does not gets it.
+ */
+class AiServicesSchemaTest {
+
+ /** Records what would have been executed. */
+ static class Recorder implements AiServicesSchema.StatementRunner {
+ final List executed = new ArrayList<>();
+ String failOn;
+
+ @Override
+ public void run(String sql) throws SQLException {
+ if (failOn != null && sql.contains(failOn)) {
+ throw new SQLException("refused: " + failOn);
+ }
+ executed.add(sql);
+ }
+ }
+
+ @Test
+ void theBundledScriptIsOnTheClasspath() {
+ assertFalse(AiServicesSchema.script().isEmpty());
+ }
+
+ @Test
+ void itParsesToOneStatement() {
+ assertEquals(1, AiServicesSchema.statements(AiServicesSchema.script()).size());
+ }
+
+ @Test
+ void thatStatementCreatesTheOwnershipTable() {
+ String only = AiServicesSchema.statements(AiServicesSchema.script()).get(0);
+
+ assertTrue(only.contains("ai_deployment"), only);
+ assertTrue(only.toUpperCase().startsWith("CREATE TABLE"), only);
+ }
+
+ @Test
+ void theLicenceHeaderIsNotExecuted() {
+ for (String statement : AiServicesSchema.statements(AiServicesSchema.script())) {
+ assertFalse(statement.contains("Licensed to the Apache"), statement);
+ }
+ }
+
+ @Test
+ void everyCreateIsIdempotent() {
+ // Startup runs this every time; a bare CREATE TABLE would turn
+ // the second restart into an error.
+ for (String statement : AiServicesSchema.statements(AiServicesSchema.script())) {
+ String upper = statement.toUpperCase();
+ if (upper.startsWith("CREATE TABLE")) {
+ assertTrue(upper.contains("IF NOT EXISTS"), statement);
+ }
+ }
+ }
+
+ @Test
+ void aSemicolonInsideAStringDoesNotSplitTheStatement() {
+ // A COMMENT holding a semicolon would otherwise be cut in half
+ // and executed as two broken statements.
+ List parsed =
+ AiServicesSchema.statements("CREATE TABLE t (a int COMMENT 'one; two');");
+
+ assertEquals(1, parsed.size(), parsed.toString());
+ }
+
+ @Test
+ void anEscapedQuoteDoesNotEndTheString() {
+ // The real script has `the engine''s identifier`.
+ List parsed =
+ AiServicesSchema.statements("CREATE TABLE t (a int COMMENT 'it''s; fine');");
+
+ assertEquals(1, parsed.size(), parsed.toString());
+ }
+
+ @Test
+ void aSemicolonInACommentDoesNotSplitEither() {
+ List parsed = AiServicesSchema.statements("-- a; comment\nCREATE TABLE t (a int);");
+
+ assertEquals(1, parsed.size(), parsed.toString());
+ }
+
+ @Test
+ void severalStatementsAreKeptInOrder() {
+ List parsed = AiServicesSchema.statements("CREATE TABLE a (x int);\nCREATE TABLE b (y int);");
+
+ assertEquals(2, parsed.size());
+ assertTrue(parsed.get(0).contains("a"));
+ assertTrue(parsed.get(1).contains("b"));
+ }
+
+ @Test
+ void anEmptyScriptRunsNothing() {
+ assertTrue(AiServicesSchema.statements("-- nothing here\n\n").isEmpty());
+ }
+
+ @Test
+ void applyRunsEveryStatement() throws Exception {
+ Recorder recorder = new Recorder();
+
+ AiServicesSchema.apply(recorder);
+
+ assertEquals(1, recorder.executed.size());
+ assertTrue(recorder.executed.get(0).contains("ai_deployment"));
+ }
+
+ @Test
+ void aFailureIsReportedRatherThanSwallowed() {
+ // The caller decides whether to abort; this must not pretend
+ // the table exists when it does not.
+ Recorder recorder = new Recorder();
+ recorder.failOn = "ai_deployment";
+
+ assertThrows(SQLException.class, () -> AiServicesSchema.apply(recorder));
+ }
+
+ @Test
+ void startupAppliesTheSchema() {
+ // Otherwise the file is back to being shipped and never run.
+ final boolean[] applied = {false};
+ AiServicesManagerImpl manager = new AiServicesManagerImpl() {
+ @Override
+ boolean applySchema() {
+ applied[0] = true;
+ return true;
+ }
+
+ @Override
+ org.apache.cloudstack.framework.events.EventBus resolveEventBus() {
+ return null; // no Spring context in a unit test
+ }
+ };
+
+ manager.start();
+
+ assertTrue(applied[0]);
+ }
+
+ @Test
+ void aSchemaFailureDoesNotStopTheManagementServer() {
+ // An optional plugin that cannot create its table must not
+ // take the whole management server down with it; the commands
+ // that need the table fail instead, and the reason is logged.
+ AiServicesManagerImpl manager = new AiServicesManagerImpl() {
+ @Override
+ boolean applySchema() {
+ return false;
+ }
+
+ @Override
+ org.apache.cloudstack.framework.events.EventBus resolveEventBus() {
+ return null;
+ }
+ };
+
+ assertTrue(manager.start());
+ }
+
+ @Test
+ void applyingTwiceIssuesTheSameStatements() {
+ // Idempotence is the database's job via IF NOT EXISTS; this
+ // only checks we do not skip on a second run and leave an
+ // upgraded schema unapplied.
+ Recorder first = new Recorder();
+ Recorder second = new Recorder();
+
+ try {
+ AiServicesSchema.apply(first);
+ AiServicesSchema.apply(second);
+ } catch (SQLException exc) {
+ throw new AssertionError(exc);
+ }
+
+ assertEquals(first.executed, second.executed);
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/CommandRegistrationTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/CommandRegistrationTest.java
new file mode 100644
index 000000000000..f1acf8524ce9
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/CommandRegistrationTest.java
@@ -0,0 +1,189 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.lang.reflect.Modifier;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.cloudstack.ai.api.command.AiServicesAsyncCmd;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.BaseAsyncCmd;
+import org.apache.cloudstack.api.BaseCmd;
+import org.junit.jupiter.api.Test;
+
+/**
+ * The whole v1 command surface (SPEC.md section 9).
+ *
+ * Section 9's table is the authoritative list. It lives as data in
+ * `aisvc/api/commands.py`, where the Python tests check it against the
+ * engine's routes; these assert the Java side of the same contract, so
+ * a command cannot exist in one place and be missing from the other.
+ */
+class CommandRegistrationTest {
+
+ /** Every v1 command name in SPEC.md section 9's table. */
+ private static final List SPEC_V1_COMMANDS = Arrays.asList(
+ "searchAiHfModels", "checkAiHfModel", "mirrorAiModel", "approveAiModel",
+ "publishAiModel", "listAiModels", "deployAiModel", "listAiModelDeployments",
+ "updateAiModelDeployment", "deleteAiModelDeployment", "promoteAiRollout",
+ "rollbackAiRollout", "listAiEndpoints", "createAiApiKey", "listAiApiKeys", "revokeAiApiKey",
+ "listAiServingProfiles", "createAiServingProfile", "updateAiServingProfile",
+ "deleteAiServingProfile", "listAiGenerationProfiles",
+ "createAiGenerationProfile", "updateAiGenerationProfile",
+ "deleteAiGenerationProfile", "assignAiTuningProfile",
+ "getAiEffectiveParameters", "listAiUsage", "listAiBudgets", "createAiBudget",
+ "updateAiBudget", "deleteAiBudget", "createAiPlaygroundSession",
+ "listAiSetupChecks", "discoverAiGpuClasses", "runAiSetupSelfTest", "listAiGpuCapacity", "drainAiNode",
+ "listAiReconcilerRuns");
+
+ /** The commands SPEC.md section 9 marks async. */
+ private static final Set ASYNC_COMMANDS = new HashSet<>(Arrays.asList(
+ "mirrorAiModel", "deployAiModel", "updateAiModelDeployment",
+ "deleteAiModelDeployment", "promoteAiRollout", "rollbackAiRollout",
+ "createAiServingProfile", "updateAiServingProfile", "deleteAiServingProfile",
+ "assignAiTuningProfile", "runAiSetupSelfTest", "drainAiNode"));
+
+ private final List> registered = new AiServicesManagerImpl().getCommands();
+
+ private Set registeredNames() {
+ Set names = new HashSet<>();
+ for (Class> command : registered) {
+ names.add(command.getAnnotation(APICommand.class).name());
+ }
+ return names;
+ }
+
+ @Test
+ void everyV1CommandInTheSpecIsRegistered() {
+ List missing = new ArrayList<>(SPEC_V1_COMMANDS);
+ missing.removeAll(registeredNames());
+
+ assertTrue(missing.isEmpty(), "commands in SPEC.md but not registered: " + missing);
+ }
+
+ @Test
+ void nothingIsRegisteredThatTheSpecDoesNotList() {
+ Set extra = new HashSet<>(registeredNames());
+ SPEC_V1_COMMANDS.forEach(extra::remove);
+
+ assertTrue(extra.isEmpty(), "registered but not in SPEC.md section 9: " + extra);
+ }
+
+ @Test
+ void theCountMatchesTheSpecsTable() {
+ assertEquals(SPEC_V1_COMMANDS.size(), registered.size());
+ }
+
+ @Test
+ void everyCommandIsConcreteAndInstantiable() {
+ for (Class> command : registered) {
+ assertFalse(Modifier.isAbstract(command.getModifiers()),
+ command.getSimpleName() + " is abstract");
+ assertTrue(BaseCmd.class.isAssignableFrom(command),
+ command.getSimpleName() + " does not extend BaseCmd");
+ }
+ }
+
+ @Test
+ void theAsyncCommandsAreTheOnesTheSpecMarksAsync() {
+ for (Class> command : registered) {
+ String name = command.getAnnotation(APICommand.class).name();
+ boolean isAsync = BaseAsyncCmd.class.isAssignableFrom(command);
+
+ assertEquals(ASYNC_COMMANDS.contains(name), isAsync,
+ name + " async mismatch: SPEC.md says "
+ + ASYNC_COMMANDS.contains(name));
+ }
+ }
+
+ @Test
+ void everyAsyncCommandUsesOurBridge() {
+ // Extending BaseAsyncCmd directly would skip the 202 check and
+ // the engine job polling.
+ for (Class> command : registered) {
+ if (BaseAsyncCmd.class.isAssignableFrom(command)) {
+ assertTrue(AiServicesAsyncCmd.class.isAssignableFrom(command),
+ command.getSimpleName() + " bypasses AiServicesAsyncCmd");
+ }
+ }
+ }
+
+ @Test
+ void everyCommandDeclaresAResponseObject() {
+ for (Class> command : registered) {
+ APICommand annotation = command.getAnnotation(APICommand.class);
+ assertNotNull(annotation.responseObject(), command.getSimpleName());
+ assertFalse(annotation.description().isEmpty(),
+ command.getSimpleName() + " has no description");
+ }
+ }
+
+ @Test
+ void onlyTheCommandsThatMintAKeyReturnSensitiveInfo() {
+ // Two, and only two. A key's secret is shown once, and marking
+ // more would suppress response logging that is useful.
+ //
+ // createAiPlaygroundSession was absent from this set, and the
+ // test passed — because the response mapping was dropping the
+ // key it mints, reading `session_key` where the engine sends
+ // `apikey`. The declaration was accidentally true, which is a
+ // bad reason for a test to be green: the command has always
+ // minted a real key, and now that the key survives the mapping
+ // the declaration has to say so.
+ Set mintsAKey = Set.of("createAiApiKey", "createAiPlaygroundSession");
+
+ for (Class> command : registered) {
+ APICommand annotation = command.getAnnotation(APICommand.class);
+
+ assertEquals(mintsAKey.contains(annotation.name()),
+ annotation.responseHasSensitiveInfo(),
+ annotation.name());
+ }
+ }
+
+ @Test
+ void noCommandRequestCarriesSensitiveInfo() {
+ // Requests carry names and ids; secrets reach the engine over
+ // mTLS from configuration, never as API parameters.
+ for (Class> command : registered) {
+ assertFalse(command.getAnnotation(APICommand.class).requestHasSensitiveInfo(),
+ command.getSimpleName());
+ }
+ }
+
+ @Test
+ void commandNamesAreUnique() {
+ assertEquals(registered.size(), registeredNames().size());
+ }
+
+ @Test
+ void everyCommandCanBeConstructed() throws Exception {
+ // CloudStack instantiates these reflectively; a missing no-arg
+ // constructor fails at request time rather than at startup.
+ for (Class> command : registered) {
+ assertNotNull(command.getDeclaredConstructor().newInstance(),
+ command.getSimpleName());
+ }
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/GeneratedSurfaceTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/GeneratedSurfaceTest.java
new file mode 100644
index 000000000000..31e30822fa85
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/GeneratedSurfaceTest.java
@@ -0,0 +1,291 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import org.mockito.ArgumentMatchers;
+import com.cloud.utils.db.EntityManager;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Stream;
+
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.BaseAsyncCmd;
+import org.apache.cloudstack.api.BaseResponse;
+import org.apache.cloudstack.api.Parameter;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/**
+ * The generated command and response surface (SPEC.md section 9).
+ *
+ * Thirty-five commands and a dozen response types are generated from one
+ * table, so they are tested the same way: systematically, over every
+ * class, rather than one file at a time. The engine objects come from
+ * `generated-engine-objects.json`, which the generator emits beside the
+ * classes so the field list is never maintained twice.
+ */
+class GeneratedSurfaceTest {
+
+ private static final JsonObject FIXTURE = loadFixture();
+
+ private static JsonObject loadFixture() {
+ try (InputStream in = GeneratedSurfaceTest.class.getClassLoader()
+ .getResourceAsStream("generated-engine-objects.json")) {
+ assertNotNull(in, "generated-engine-objects.json is missing; run the generator");
+ return JsonParser.parseReader(
+ new InputStreamReader(in, StandardCharsets.UTF_8)).getAsJsonObject();
+ } catch (Exception failure) {
+ throw new IllegalStateException("could not read the engine fixture", failure);
+ }
+ }
+
+ static Stream> commands() {
+ return new AiServicesManagerImpl().getCommands().stream();
+ }
+
+ static Stream responseNames() {
+ return FIXTURE.keySet().stream();
+ }
+
+ // -- responses --------------------------------------------------------
+
+ @ParameterizedTest
+ @MethodSource("responseNames")
+ void everyFieldOfAnEngineObjectIsMapped(String responseName) throws Exception {
+ Class> type = Class.forName(
+ "org.apache.cloudstack.ai.api.response." + responseName);
+ Method from = type.getMethod("from", JsonObject.class);
+
+ Object mapped = from.invoke(null, FIXTURE.getAsJsonObject(responseName));
+
+ assertNotNull(mapped);
+ for (Field field : type.getDeclaredFields()) {
+ if (field.isSynthetic() || java.lang.reflect.Modifier.isStatic(
+ field.getModifiers())) {
+ continue;
+ }
+ field.setAccessible(true);
+ assertNotNull(field.get(mapped),
+ responseName + "." + field.getName() + " was not mapped");
+ }
+ }
+
+ @ParameterizedTest
+ @MethodSource("responseNames")
+ void anEmptyEngineObjectMapsWithoutFailing(String responseName) throws Exception {
+ Class> type = Class.forName(
+ "org.apache.cloudstack.ai.api.response." + responseName);
+ Method from = type.getMethod("from", JsonObject.class);
+
+ assertNotNull(from.invoke(null, new JsonObject()));
+ }
+
+ @ParameterizedTest
+ @MethodSource("responseNames")
+ void aNullEngineObjectStillYieldsANamedResponse(String responseName)
+ throws Exception {
+ Class> type = Class.forName(
+ "org.apache.cloudstack.ai.api.response." + responseName);
+ Method from = type.getMethod("from", JsonObject.class);
+
+ BaseResponse mapped = (BaseResponse) from.invoke(null, (JsonObject) null);
+
+ assertNotNull(mapped.getObjectName(),
+ responseName + " must name itself for the serialiser");
+ }
+
+ // -- commands ---------------------------------------------------------
+
+ /** Fill every declared @Parameter so paths and bodies are exercised. */
+ private static Object populate(Class> command) throws Exception {
+ Object instance = command.getDeclaredConstructor().newInstance();
+ // A command with a typed entity parameter resolves it through
+ // `_entityMgr` before building its body, so without one every
+ // such command fails here with a NullPointerException that
+ // says nothing about the command. Only v1 commands are listed
+ // while `ai.services.v2.enabled` is off, which is why this was
+ // not needed until a v1 command started resolving.
+ EntityManager entities = mock(EntityManager.class);
+ when(entities.findById(ArgumentMatchers.>any(), any()))
+ .thenAnswer(found -> mock(found.getArgument(0, Class.class)));
+ setEntityManager(instance, entities);
+
+ for (Field field : command.getDeclaredFields()) {
+ if (field.getAnnotation(Parameter.class) == null) {
+ continue;
+ }
+ field.setAccessible(true);
+ Class> type = field.getType();
+ if (type == String.class) {
+ field.set(instance, "sample");
+ } else if (type == Integer.class) {
+ field.set(instance, 7);
+ } else if (type == Long.class) {
+ field.set(instance, 7L);
+ } else if (type == Boolean.class) {
+ field.set(instance, Boolean.TRUE);
+ }
+ }
+ return instance;
+ }
+
+ /** Set `BaseCmd._entityMgr`, wherever it sits in the hierarchy. */
+ private static void setEntityManager(Object instance, EntityManager entities)
+ throws Exception {
+ for (Class> current = instance.getClass();
+ current != null;
+ current = current.getSuperclass()) {
+ try {
+ Field field = current.getDeclaredField("_entityMgr");
+ field.setAccessible(true);
+ field.set(instance, entities);
+ return;
+ } catch (NoSuchFieldException keepLooking) {
+ continue;
+ }
+ }
+ }
+
+ private static String enginePathOf(Object command) throws Exception {
+ Method path = findMethod(command.getClass(), "enginePath");
+ path.setAccessible(true);
+ return (String) path.invoke(command);
+ }
+
+ private static Method findMethod(Class> type, String name) throws Exception {
+ for (Class> current = type; current != null; current = current.getSuperclass()) {
+ try {
+ return current.getDeclaredMethod(name);
+ } catch (NoSuchMethodException keepLooking) {
+ continue;
+ }
+ }
+ throw new NoSuchMethodException(name + " on " + type.getName());
+ }
+
+ @ParameterizedTest
+ @MethodSource("commands")
+ void everyCommandBuildsAVersionedEnginePath(Class> command) throws Exception {
+ String path = enginePathOf(populate(command));
+
+ assertTrue(path.startsWith("/v1/"), command.getSimpleName() + " -> " + path);
+ }
+
+ @ParameterizedTest
+ @MethodSource("commands")
+ void noPathPlaceholderSurvivesIntoTheRequest(Class> command) throws Exception {
+ // An unsubstituted {id} would be sent to the engine literally.
+ String path = enginePathOf(populate(command));
+
+ assertFalse(path.contains("{"), command.getSimpleName() + " -> " + path);
+ assertFalse(path.contains("}"), command.getSimpleName() + " -> " + path);
+ }
+
+ @ParameterizedTest
+ @MethodSource("commands")
+ void everyCommandUsesAKnownVerb(Class> command) throws Exception {
+ Method method = findMethod(command, "engineMethod");
+ method.setAccessible(true);
+ String verb = (String) method.invoke(populate(command));
+
+ assertTrue(
+ List.of("GET", "POST", "PATCH", "DELETE").contains(verb),
+ command.getSimpleName() + " uses " + verb);
+ }
+
+ @ParameterizedTest
+ @MethodSource("commands")
+ void aBodyCarryingCommandProducesValidJson(Class> command) throws Exception {
+ Method body = findMethod(command, "engineBody");
+ body.setAccessible(true);
+ String rendered = (String) body.invoke(populate(command));
+
+ if (rendered != null) {
+ assertTrue(JsonParser.parseString(rendered).isJsonObject(),
+ command.getSimpleName() + " body is not an object");
+ }
+ }
+
+ @ParameterizedTest
+ @MethodSource("commands")
+ void readsCarryNoBody(Class> command) throws Exception {
+ Method method = findMethod(command, "engineMethod");
+ method.setAccessible(true);
+ Object instance = populate(command);
+
+ if ("GET".equals(method.invoke(instance)) || "DELETE".equals(method.invoke(instance))) {
+ Method body = findMethod(command, "engineBody");
+ body.setAccessible(true);
+ assertEquals(null, body.invoke(instance),
+ command.getSimpleName() + " sends a body on a read");
+ }
+ }
+
+ @Test
+ void theFixtureCoversEveryGeneratedResponse() {
+ // A new response type without a fixture entry would be untested.
+ List missing = new ArrayList<>();
+ for (Map.Entry entry : FIXTURE.entrySet()) {
+ if (entry.getValue().getAsJsonObject().size() == 0) {
+ missing.add(entry.getKey());
+ }
+ }
+
+ assertTrue(missing.isEmpty(), "fixture entries with no fields: " + missing);
+ }
+
+ @Test
+ void asyncCommandsDeclareAnEventTypeAndDescription() throws Exception {
+ for (Class> command : new AiServicesManagerImpl().getCommands()) {
+ if (!BaseAsyncCmd.class.isAssignableFrom(command)) {
+ continue;
+ }
+ BaseAsyncCmd instance = (BaseAsyncCmd) populate(command);
+
+ assertTrue(instance.getEventType().startsWith("AI."),
+ command.getSimpleName() + " event: " + instance.getEventType());
+ assertFalse(instance.getEventDescription().isEmpty(),
+ command.getSimpleName() + " has no event description");
+ }
+ }
+
+ @Test
+ void everyCommandNameMatchesItsClassName() {
+ for (Class> command : new AiServicesManagerImpl().getCommands()) {
+ String name = command.getAnnotation(APICommand.class).name();
+ String expected = Character.toUpperCase(name.charAt(0)) + name.substring(1) + "Cmd";
+
+ assertEquals(expected, command.getSimpleName());
+ }
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/SpringContextTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/SpringContextTest.java
new file mode 100644
index 000000000000..a56c144c5257
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/SpringContextTest.java
@@ -0,0 +1,129 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import javax.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Everything the plugin injects from its own packages must be a bean.
+ *
+ *
CloudStack's core context supplies its own DAOs — DomainDao,
+ * HostDao, VMInstanceDao — but a type this plugin defines is one only
+ * this plugin's context can declare. The context declared the manager
+ * and nothing else, so a real management server found the module,
+ * tried to build it and gave up:
+ *
+ *
+ * Failed to load module [ai-services]: Error creating bean
+ * 'aiServicesManagerImpl': Unsatisfied dependency 'deploymentDao';
+ * No qualifying bean of type 'org.apache.cloudstack.ai.dao.AiDeploymentDao'
+ *
+ *
+ *
Nothing caught it because no unit test builds the Spring context;
+ * they construct the manager directly and set its fields. Only loading
+ * the plugin into CloudStack could show it, and this is the cheap
+ * guard that keeps it shown.
+ */
+class SpringContextTest {
+
+ private static final String CONTEXT =
+ "META-INF/cloudstack/ai-services/spring-ai-services-context.xml";
+
+ private static String contextXml() throws Exception {
+ try (InputStream in =
+ SpringContextTest.class.getClassLoader().getResourceAsStream(CONTEXT)) {
+ if (in == null) {
+ throw new IllegalStateException(CONTEXT + " is not on the classpath");
+ }
+ return new String(in.readAllBytes(), StandardCharsets.UTF_8);
+ }
+ }
+
+ private static List declaredClasses(String xml) {
+ List found = new ArrayList<>();
+ Matcher m = Pattern.compile("class=\"([^\"]+)\"").matcher(xml);
+ while (m.find()) {
+ found.add(m.group(1));
+ }
+ return found;
+ }
+
+ /** Types this plugin owns, which only its own context can supply. */
+ private static boolean ours(Class> type) {
+ return type.getName().startsWith("org.apache.cloudstack.ai.");
+ }
+
+ @Test
+ void everyInjectedTypeThisPluginOwnsHasABean() throws Exception {
+ List declared = declaredClasses(contextXml());
+
+ List missing = new ArrayList<>();
+ for (Field field : AiServicesManagerImpl.class.getDeclaredFields()) {
+ if (field.getAnnotation(Inject.class) == null || !ours(field.getType())) {
+ continue;
+ }
+ boolean satisfied = declared.stream().anyMatch(name -> {
+ try {
+ return field.getType().isAssignableFrom(Class.forName(name));
+ } catch (ClassNotFoundException absent) {
+ return false;
+ }
+ });
+ if (!satisfied) {
+ missing.add(field.getType().getName());
+ }
+ }
+
+ assertTrue(missing.isEmpty(),
+ "no bean declared for " + missing + " in " + CONTEXT
+ + "; CloudStack will refuse to load the module");
+ }
+
+ @Test
+ void theManagerItselfIsDeclared() throws Exception {
+ assertTrue(declaredClasses(contextXml())
+ .contains(AiServicesManagerImpl.class.getName()));
+ }
+
+ @Test
+ void everyDeclaredBeanClassExists() throws Exception {
+ // A typo in the XML is the same outage, found at startup
+ // rather than at compile time.
+ List absent = new ArrayList<>();
+ for (String name : declaredClasses(contextXml())) {
+ try {
+ Class.forName(name);
+ } catch (ClassNotFoundException missing) {
+ absent.add(name);
+ }
+ }
+
+ assertFalse(declaredClasses(contextXml()).isEmpty(), "no beans declared at all");
+ assertTrue(absent.isEmpty(), "declared but not on the classpath: " + absent);
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/V2CommandRegistrationTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/V2CommandRegistrationTest.java
new file mode 100644
index 000000000000..c7874a7a9f78
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/V2CommandRegistrationTest.java
@@ -0,0 +1,124 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tier 2 commands are generated but off by default (SPEC.md section 8).
+ *
+ *
The engine marks these {@code Release.V2} in {@code commands.py},
+ * and that boundary has to hold on this side too: a GA install should
+ * not grow an API surface for features it does not run. The global
+ * setting {@code ai.services.v2.enabled} turns them on, so an operator
+ * can exercise v2 without a separate build.
+ */
+class V2CommandRegistrationTest {
+
+ /** Every v2 command, as aisvc/api/commands.py names them. */
+ private static final Set V2_COMMANDS = Set.of(
+ "listAiAdapters", "uploadAiAdapter", "deleteAiAdapter",
+ "createAiBatch", "listAiBatches", "cancelAiBatch", "getAiBatchResults",
+ "listAiGuardrailProfiles", "createAiGuardrailProfile",
+ "updateAiGuardrailProfile", "deleteAiGuardrailProfile",
+ "runAiModelEvaluation", "listAiEvaluations",
+ "uploadAiCertificate", "listAiCertificates", "replaceAiCertificate",
+ "deleteAiCertificate",
+ "listAiPrivateEndpoints", "createAiPrivateEndpoint", "deleteAiPrivateEndpoint");
+
+ /** The production path: no ConfigDepot in a unit test, so the key reads its default. */
+ private Set asShipped() {
+ return names(new AiServicesManagerImpl());
+ }
+
+ /** The same manager with the setting turned on. */
+ private Set withV2() {
+ return names(new AiServicesManagerImpl() {
+ @Override
+ boolean v2Enabled() {
+ return true;
+ }
+ });
+ }
+
+ private static Set names(AiServicesManagerImpl manager) {
+ return manager.getCommands().stream()
+ .map(Class::getSimpleName)
+ .collect(Collectors.toSet());
+ }
+
+ private static String className(String apiName) {
+ return Character.toUpperCase(apiName.charAt(0)) + apiName.substring(1) + "Cmd";
+ }
+
+ @Test
+ void v2CommandsAreAbsentByDefault() {
+ Set registered = asShipped();
+
+ for (String command : V2_COMMANDS) {
+ assertFalse(registered.contains(className(command)),
+ command + " should not be registered unless v2 is enabled");
+ }
+ }
+
+ @Test
+ void v2CommandsAppearWhenEnabled() {
+ Set registered = withV2();
+
+ for (String command : V2_COMMANDS) {
+ assertTrue(registered.contains(className(command)),
+ command + " should be registered when v2 is enabled");
+ }
+ }
+
+ @Test
+ void enablingV2LeavesTheGaSurfaceAlone() {
+ // Turning v2 on adds; it must never take away or replace.
+ assertTrue(withV2().containsAll(asShipped()));
+ }
+
+ @Test
+ void enablingV2AddsNothingButV2() {
+ Set shipped = asShipped();
+ List added = withV2().stream()
+ .filter(name -> !shipped.contains(name))
+ .sorted()
+ .collect(Collectors.toList());
+
+ assertEquals(
+ V2_COMMANDS.stream().map(V2CommandRegistrationTest::className).sorted()
+ .collect(Collectors.toList()),
+ added);
+ }
+
+ @Test
+ void theSettingIsOffByDefault() {
+ assertFalse(Boolean.parseBoolean(AiServicesConfig.V2Enabled.defaultValue()));
+ }
+
+ @Test
+ void theSettingIsExported() {
+ assertTrue(Arrays.asList(AiServicesConfig.all()).contains(AiServicesConfig.V2Enabled));
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiCommandsTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiCommandsTest.java
new file mode 100644
index 000000000000..7757102086c4
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiCommandsTest.java
@@ -0,0 +1,221 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.lang.reflect.Field;
+
+import org.apache.cloudstack.ai.AiServicesEvents;
+import org.apache.cloudstack.ai.api.response.AiDeploymentResponse;
+import org.apache.cloudstack.ai.engine.EngineException;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.ApiErrorCode;
+import org.apache.cloudstack.api.BaseAsyncCmd;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import com.cloud.dc.DataCenter;
+import com.cloud.exception.InvalidParameterValueException;
+import com.cloud.utils.db.EntityManager;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/** The async commands and the engine-error mapping (SPEC.md section 9). */
+class AiCommandsTest {
+
+ private static void set(Object target, String field, Object value) throws Exception {
+ Field declared = target.getClass().getDeclaredField(field);
+ declared.setAccessible(true);
+ declared.set(target, value);
+ }
+
+ @Test
+ void deployIsAnAsyncCommand() {
+ assertTrue(BaseAsyncCmd.class.isAssignableFrom(DeployAiModelCmd.class));
+ assertEquals("deployAiModel",
+ DeployAiModelCmd.class.getAnnotation(APICommand.class).name());
+ }
+
+ @Test
+ void deployEmitsTheSpecifiedEvent() {
+ assertEquals(AiServicesEvents.MODEL_DEPLOY, new DeployAiModelCmd().getEventType());
+ }
+
+ @Test
+ void deployPostsToTheDeploymentsEndpoint() {
+ DeployAiModelCmd command = new DeployAiModelCmd();
+
+ assertEquals("/v1/deployments", command.enginePath());
+ assertEquals("POST", command.engineMethod());
+ }
+
+ /** A command whose zone id resolves to a CloudStack zone by that name. */
+ private static DeployAiModelCmd deployIn(long zoneId, String zoneName) throws Exception {
+ DeployAiModelCmd command = new DeployAiModelCmd();
+ set(command, "zoneId", zoneId);
+ DataCenter zone = mock(DataCenter.class);
+ when(zone.getName()).thenReturn(zoneName);
+ EntityManager entities = mock(EntityManager.class);
+ when(entities.findById(DataCenter.class, zoneId)).thenReturn(zone);
+ command._entityMgr = entities;
+ return command;
+ }
+
+ @Test
+ void deployCarriesTheModelAndTheZonesNameInItsBody() throws Exception {
+ // The *name*, not the id. `zoneid` is a CommandType.UUID, which
+ // CloudStack hands back as its internal numeric id, and the
+ // engine knows zones by the name platform.yaml records in
+ // `cloudstack_zone`. Sending the raw Long was answered with a
+ // 422 by a live engine, and this test pinned it in place by
+ // asserting the number.
+ DeployAiModelCmd command = deployIn(4L, "East-1");
+ set(command, "modelName", "llama-3.3-70b-instruct");
+
+ JsonObject body = JsonParser.parseString(command.engineBody()).getAsJsonObject();
+
+ assertEquals("llama-3.3-70b-instruct", body.get("model").getAsString());
+ assertEquals("East-1", body.get("zone_id").getAsString());
+ }
+
+ @Test
+ void deployRefusesAZoneCloudStackCannotFind() throws Exception {
+ DeployAiModelCmd command = new DeployAiModelCmd();
+ set(command, "modelName", "m");
+ set(command, "zoneId", 9L);
+ command._entityMgr = mock(EntityManager.class);
+
+ assertThrows(InvalidParameterValueException.class, command::engineBody);
+ }
+
+ @Test
+ void anUnsetReplicaCountIsOmittedRatherThanSentAsZero() throws Exception {
+ // Zero would scale the deployment to nothing; absent lets the
+ // engine use the model's declared minimum.
+ DeployAiModelCmd command = deployIn(1L, "East-1");
+ set(command, "modelName", "m");
+
+ JsonObject body = JsonParser.parseString(command.engineBody()).getAsJsonObject();
+
+ assertFalse(body.has("replicas"));
+ }
+
+ @Test
+ void anExplicitReplicaCountIsSent() throws Exception {
+ DeployAiModelCmd command = deployIn(1L, "East-1");
+ set(command, "modelName", "m");
+ set(command, "replicas", 3);
+
+ JsonObject body = JsonParser.parseString(command.engineBody()).getAsJsonObject();
+
+ assertEquals(3, body.get("replicas").getAsInt());
+ }
+
+ @Test
+ void deployDescribesWhatItIsDoing() throws Exception {
+ DeployAiModelCmd command = new DeployAiModelCmd();
+ set(command, "modelName", "llama");
+
+ assertTrue(command.getEventDescription().contains("llama"));
+ }
+
+ @Test
+ void deleteUsesTheDeleteVerbAgainstTheDeployment() throws Exception {
+ DeleteAiModelDeploymentCmd command = new DeleteAiModelDeploymentCmd();
+ set(command, "deploymentId", "d-1");
+
+ assertEquals("/v1/deployments/d-1", command.enginePath());
+ assertEquals("DELETE", command.engineMethod());
+ assertNull(command.engineBody());
+ }
+
+ @Test
+ void deleteEmitsTheSpecifiedEvent() {
+ assertEquals(AiServicesEvents.MODEL_DELETE,
+ new DeleteAiModelDeploymentCmd().getEventType());
+ }
+
+ @ParameterizedTest
+ @CsvSource({
+ "400, PARAM_ERROR",
+ "422, PARAM_ERROR",
+ "404, PARAM_ERROR",
+ "403, ACCOUNT_ERROR",
+ "503, RESOURCE_UNAVAILABLE_ERROR",
+ "500, INTERNAL_ERROR",
+ "0, INTERNAL_ERROR",
+ })
+ void engineErrorsMapOntoCloudStackCodes(int status, String expected) {
+ // A 403 is a permission decision; reporting it as an internal
+ // error would hide from the tenant why their call failed.
+ ApiErrorCode mapped =
+ AiServicesAsyncCmd.errorCodeFor(new EngineException("x", status, null));
+
+ assertEquals(expected, mapped.name());
+ }
+
+ @Test
+ void aDeploymentResponseIsBuiltFromAJobResult() {
+ JsonObject result = JsonParser.parseString(
+ "{\"deployment\": {\"id\": \"d-1\", \"model\": \"llama\","
+ + " \"colour\": \"blue\", \"replicas_desired\": 2,"
+ + " \"replicas_ready\": 1, \"state\": \"Running\"}}")
+ .getAsJsonObject();
+
+ AiDeploymentResponse response = AiDeploymentResponse.from(result);
+
+ assertEquals("d-1", response.getId());
+ assertEquals("llama", response.getModel());
+ assertEquals("blue", response.getColour());
+ assertEquals(2, response.getReplicasDesired());
+ assertEquals(1, response.getReplicasReady());
+ assertEquals("Running", response.getState());
+ }
+
+ @Test
+ void aFlatDeploymentObjectWorksToo() {
+ JsonObject result = JsonParser.parseString(
+ "{\"id\": \"d-2\", \"model\": \"m\"}").getAsJsonObject();
+
+ assertEquals("d-2", AiDeploymentResponse.from(result).getId());
+ }
+
+ @Test
+ void anEmptyJobResultStillYieldsAResponse() {
+ AiDeploymentResponse response = AiDeploymentResponse.from(null);
+
+ assertNotNull(response);
+ assertEquals("aideployment", response.getObjectName());
+ assertNull(response.getId());
+ }
+
+ @Test
+ void missingFieldsAreNullRatherThanAnError() {
+ AiDeploymentResponse response = AiDeploymentResponse.from(
+ JsonParser.parseString("{\"id\": \"d-3\"}").getAsJsonObject());
+
+ assertNull(response.getReplicasReady());
+ assertNull(response.getState());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmdTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmdTest.java
new file mode 100644
index 000000000000..e26618a235d5
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesAsyncCmdTest.java
@@ -0,0 +1,201 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.cloudstack.ai.AiServicesService;
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.ai.engine.EngineClient;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.ai.engine.EngineTransport;
+import org.apache.cloudstack.api.ServerApiException;
+import org.junit.jupiter.api.Test;
+
+/**
+ * The async bridge (SPEC.md section 9).
+ *
+ * A 202 is the contract: anything else means the engine did not accept
+ * the command, and treating a 200 as success would report work that
+ * never started.
+ */
+class AiServicesAsyncCmdTest {
+
+ private static final CallerContext CALLER =
+ new CallerContext("u", "acme", "/Customers/Acme", "User");
+
+ /** A minimal async command that records what it was given. */
+ private static final class TestCmd extends AiServicesAsyncCmd {
+ EngineJob finished;
+
+ @Override
+ protected String enginePath() {
+ return "/v1/deployments";
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ this.finished = job;
+ }
+
+ @Override
+ public String getEventType() {
+ return "AI.TEST";
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "a test command";
+ }
+ }
+
+ /** Answers the POST, then the job polls, from a script. */
+ private static EngineClient clientReturning(List answers) {
+ List remaining = new ArrayList<>(answers);
+ EngineTransport transport = (method, url, headers, body) ->
+ remaining.isEmpty() ? answers.get(answers.size() - 1) : remaining.remove(0);
+ return new EngineClient(Collections.singletonList("https://engine"), transport);
+ }
+
+ private static TestCmd commandOver(List answers) throws Exception {
+ TestCmd command = new TestCmd();
+ AiServicesService service = mock(AiServicesService.class);
+ when(service.getEngineClient()).thenReturn(clientReturning(answers));
+ when(service.currentCaller()).thenReturn(CALLER);
+ // Every async command now runs its work inside the manager, so
+ // CloudStack records whether it finished; the real one is a
+ // Spring proxy carrying @ActionEvent. Here it only has to let
+ // the work through — EventRecordingTest is what checks that
+ // the command routes through it at all.
+ doAnswer(invocation -> {
+ ((Runnable) invocation.getArgument(2)).run();
+ return null;
+ }).when(service).recordEvent(anyString(), anyString(), any(Runnable.class));
+
+ Field field = AiServicesAsyncCmd.class.getDeclaredField("aiServices");
+ field.setAccessible(true);
+ field.set(command, service);
+ return command;
+ }
+
+ @Test
+ void anAcceptedCommandIsPolledToCompletion() throws Exception {
+ TestCmd command = commandOver(java.util.Arrays.asList(
+ new EngineResponse(202, "{\"jobid\": \"j-1\"}"),
+ new EngineResponse(200,
+ "{\"jobid\": \"j-1\", \"jobstatus\": 1,"
+ + " \"jobresult\": {\"deployment\": {\"id\": \"d-1\"}}}")));
+
+ command.execute();
+
+ assertTrue(command.finished.isSuccess());
+ assertEquals("j-1", command.finished.getJobId());
+ }
+
+ @Test
+ void a200IsNotTreatedAsAcceptance() throws Exception {
+ // The engine answered without starting a job; reporting success
+ // would claim work that never happened.
+ TestCmd command = commandOver(Collections.singletonList(
+ new EngineResponse(200, "{\"jobid\": \"j-1\"}")));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("did not accept"));
+ }
+
+ @Test
+ void aRefusedCommandSaysWhyTheEngineRefused() throws Exception {
+ // The sync path learned this from a live round trip; the async
+ // path had the same defect from the same cause. A batch the
+ // engine refused reported only
+ //
+ // the AI Services engine did not accept AI.BATCH.CREATE: HTTP 400
+ //
+ // while the body said which field was wrong. The engine speaks
+ // RFC 9457 so its caller can explain itself, and both paths
+ // now ask EngineResponse the same question.
+ TestCmd command = commandOver(Collections.singletonList(
+ new EngineResponse(400,
+ "{\"title\":\"bad request\",\"detail\":\"model is not deployed\"}")));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("model is not deployed"),
+ "lost the engine's detail: " + failure.getDescription());
+ }
+
+ @Test
+ void aRefusalKeepsItsStatusBesideTheDetail() throws Exception {
+ TestCmd command = commandOver(Collections.singletonList(
+ new EngineResponse(400, "{\"detail\":\"model is not deployed\"}")));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("400"), failure.getDescription());
+ }
+
+ @Test
+ void aRefusedCommandSurfacesItsStatus() throws Exception {
+ TestCmd command = commandOver(Collections.singletonList(
+ new EngineResponse(403, "{}")));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("403"));
+ }
+
+ @Test
+ void aFailedEngineJobBecomesAServerApiException() throws Exception {
+ TestCmd command = commandOver(java.util.Arrays.asList(
+ new EngineResponse(202, "{\"jobid\": \"j-1\"}"),
+ new EngineResponse(200,
+ "{\"jobid\": \"j-1\", \"jobstatus\": 2, \"jobresult\":"
+ + " {\"errortext\": \"Insufficient capacity\","
+ + " \"errorcode\": 533}}")));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("Insufficient capacity"));
+ }
+
+ @Test
+ void theDefaultVerbIsPost() {
+ assertEquals("POST", new TestCmd().engineMethod());
+ }
+
+ @Test
+ void thereIsNoBodyByDefault() {
+ org.junit.jupiter.api.Assertions.assertNull(new TestCmd().engineBody());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmdTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmdTest.java
new file mode 100644
index 000000000000..4975045f9e52
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/AiServicesSyncCmdTest.java
@@ -0,0 +1,318 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Field;
+import java.util.Collections;
+
+import org.apache.cloudstack.ai.AiServicesService;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.ai.engine.EngineClient;
+import org.apache.cloudstack.ai.engine.EngineException;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.ai.engine.EngineTransport;
+import org.apache.cloudstack.api.ApiErrorCode;
+import org.apache.cloudstack.api.ServerApiException;
+import org.apache.cloudstack.api.response.ListResponse;
+import org.junit.jupiter.api.Test;
+
+import com.google.gson.JsonObject;
+
+/** Synchronous and list commands against a scripted engine. */
+class AiServicesSyncCmdTest {
+
+ private static final CallerContext CALLER =
+ new CallerContext("u", "acme", "/Customers/Acme", "User");
+
+ private static final class TestListCmd extends AiServicesListCmd {
+ @Override
+ protected String enginePath() {
+ return "/v1/models";
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "models";
+ }
+
+ @Override
+ protected AiModelResponse mapItem(JsonObject item) {
+ return AiModelResponse.from(item);
+ }
+ }
+
+ /** A list whose screen has a detail view, matching on the model's name. */
+ private static final class TestFilteringListCmd extends AiServicesListCmd {
+ @Override
+ protected String enginePath() {
+ return "/v1/models";
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "models";
+ }
+
+ @Override
+ protected boolean filtersById() {
+ return true;
+ }
+
+ @Override
+ protected String identityField() {
+ return "name";
+ }
+
+ @Override
+ protected AiModelResponse mapItem(JsonObject item) {
+ return AiModelResponse.from(item);
+ }
+ }
+
+ private static void askFor(AiServicesListCmd> command, String id) throws Exception {
+ Field field = AiServicesListCmd.class.getDeclaredField("id");
+ field.setAccessible(true);
+ field.set(command, id);
+ }
+
+ private static T wire(T command, EngineResponse answer) throws Exception {
+ AiServicesService service = mock(AiServicesService.class);
+ EngineTransport transport = (method, url, headers, body) -> answer;
+ when(service.getEngineClient()).thenReturn(
+ new EngineClient(Collections.singletonList("https://engine"), transport));
+ when(service.currentCaller()).thenReturn(CALLER);
+
+ Field field = AiServicesSyncCmd.class.getDeclaredField("aiServices");
+ field.setAccessible(true);
+ field.set(command, service);
+ return command;
+ }
+
+ @SuppressWarnings("unchecked")
+ private static ListResponse listOf(TestListCmd command) {
+ return (ListResponse) command.getResponseObject();
+ }
+
+ @Test
+ void aListCommandMapsEveryItem() throws Exception {
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(200,
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"a\"}, {\"name\": \"b\"}]}"));
+
+ command.execute();
+
+ assertEquals(2, listOf(command).getCount());
+ }
+
+ @Test
+ void anEmptyCollectionIsAnEmptyList() throws Exception {
+ TestListCmd command =
+ wire(new TestListCmd(), new EngineResponse(200, "{\"models\": []}"));
+
+ command.execute();
+
+ assertEquals(0, listOf(command).getCount());
+ }
+
+ @Test
+ void aMissingCollectionIsAnEmptyListNotAFailure() throws Exception {
+ // An engine that returns {} has nothing for this caller to see,
+ // which is a legitimate answer under caller-context filtering.
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(200, "{}"));
+
+ command.execute();
+
+ assertEquals(0, listOf(command).getCount());
+ }
+
+ @Test
+ void nonObjectEntriesAreSkippedRatherThanCrashing() throws Exception {
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(200,
+ "{\"models\": [{\"name\": \"a\"}, \"junk\", 7]}"));
+
+ command.execute();
+
+ assertEquals(1, listOf(command).getCount());
+ }
+
+ @Test
+ void aForbiddenEngineAnswerBecomesAnAccountError() throws Exception {
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(403, "{}"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertEquals(ApiErrorCode.ACCOUNT_ERROR, failure.getErrorCode());
+ }
+
+ @Test
+ void anUnavailableEngineBecomesAResourceError() throws Exception {
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(503, "{}"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("503"));
+ }
+
+ @Test
+ void theEnginesOwnExplanationReachesTheOperator() throws Exception {
+ // Found by the first end-to-end round trip. listAiGpuCapacity
+ // reported "the AI Services engine returned 503 for
+ // /v1/capacity" while the engine had said, in the body,
+ // "capacity has not been observed yet" — which is the
+ // sentence that tells an operator to run a reconcile.
+ //
+ // The engine answers in RFC 9457 problem JSON precisely so
+ // its callers can say why. The plugin is its only caller.
+ TestListCmd command = wire(
+ new TestListCmd(),
+ new EngineResponse(503, "{\"title\":\"unavailable\","
+ + "\"detail\":\"capacity has not been observed yet\"}"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("capacity has not been observed yet"),
+ "lost the engine's detail: " + failure.getDescription());
+ }
+
+ @Test
+ void theStatusAndPathSurviveAlongsideTheDetail() throws Exception {
+ // The detail is added to what was already there, not swapped
+ // for it: the status is what an operator greps for.
+ TestListCmd command = wire(
+ new TestListCmd(),
+ new EngineResponse(503, "{\"detail\":\"capacity has not been observed yet\"}"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("503"), failure.getDescription());
+ }
+
+ @Test
+ void aProblemWithNoDetailFallsBackToTheTitle() throws Exception {
+ TestListCmd command =
+ wire(new TestListCmd(), new EngineResponse(500, "{\"title\":\"internal error\"}"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("internal error"), failure.getDescription());
+ }
+
+ @Test
+ void anUnparseableErrorBodyStillReportsTheStatus() throws Exception {
+ // A body that is not problem JSON must not turn a clean
+ // failure into a parse failure: the status is still the
+ // useful thing, and this path is reached when something
+ // other than the engine answers — a proxy, a load balancer.
+ TestListCmd command =
+ wire(new TestListCmd(), new EngineResponse(502, "Bad Gateway"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("502"), failure.getDescription());
+ }
+
+ @Test
+ void anUnreadableBodyIsReportedClearly() throws Exception {
+ TestListCmd command =
+ wire(new TestListCmd(), new EngineResponse(200, "nope"));
+
+ ServerApiException failure =
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertTrue(failure.getDescription().contains("unreadable"));
+ }
+
+ @Test
+ void anEmptyBodyParsesAsAnEmptyObject() {
+ assertEquals(0, AiServicesSyncCmd.parse("").size());
+ assertEquals(0, AiServicesSyncCmd.parse(null).size());
+ }
+
+ @Test
+ void parsingRejectsNonJson() {
+ assertThrows(EngineException.class, () -> AiServicesSyncCmd.parse("nope"));
+ }
+
+ @Test
+ void aDetailViewGetsTheRowItAskedFor() throws Exception {
+ // CloudStack opens a detail page by calling the same list command
+ // with id=. Before this the parameter was dropped,
+ // the engine answered with everything, and AutogenView drew the
+ // first row — so every detail page showed the first record in its
+ // list, whatever had been clicked.
+ TestFilteringListCmd command = wire(new TestFilteringListCmd(), new EngineResponse(200,
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"a\"}, {\"name\": \"b\"}]}"));
+ askFor(command, "b");
+
+ command.execute();
+
+ ListResponse listed =
+ (ListResponse) command.getResponseObject();
+ assertEquals(1, listed.getCount());
+ assertEquals("b", listed.getResponses().get(0).getName());
+ }
+
+ @Test
+ void aListWithNoIdIsTheWholeList() throws Exception {
+ TestFilteringListCmd command = wire(new TestFilteringListCmd(), new EngineResponse(200,
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"a\"}, {\"name\": \"b\"}]}"));
+
+ command.execute();
+
+ assertEquals(2, ((ListResponse>) command.getResponseObject()).getCount());
+ }
+
+ @Test
+ void anIdMatchingNothingIsAnEmptyList() throws Exception {
+ // Not the first row, which is the failure being fixed.
+ TestFilteringListCmd command = wire(new TestFilteringListCmd(), new EngineResponse(200,
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"a\"}, {\"name\": \"b\"}]}"));
+ askFor(command, "gone");
+
+ command.execute();
+
+ assertEquals(0, ((ListResponse>) command.getResponseObject()).getCount());
+ }
+
+ @Test
+ void aListWithNoDetailViewIgnoresAnIdRatherThanEmptyingItself() throws Exception {
+ // filtersById() is false by default. A screen with no detail page is
+ // never called with an id, and filtering one that is would silently
+ // empty a list that used to work.
+ TestListCmd command = wire(new TestListCmd(), new EngineResponse(200,
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"a\"}, {\"name\": \"b\"}]}"));
+
+ command.execute();
+
+ assertEquals(2, listOf(command).getCount());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/EventRecordingTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/EventRecordingTest.java
new file mode 100644
index 000000000000..92731cee1c18
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/EventRecordingTest.java
@@ -0,0 +1,264 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.cloudstack.ai.AiServicesManagerImpl;
+import org.apache.cloudstack.ai.AiServicesService;
+import org.apache.cloudstack.ai.api.response.AiModelResponse;
+import org.apache.cloudstack.ai.engine.CallerContext;
+import org.apache.cloudstack.ai.engine.EngineClient;
+import org.apache.cloudstack.ai.engine.EngineJob;
+import org.apache.cloudstack.ai.engine.EngineResponse;
+import org.apache.cloudstack.ai.engine.EngineTransport;
+import org.apache.cloudstack.api.ServerApiException;
+import org.junit.jupiter.api.Test;
+
+import com.cloud.event.ActionEvent;
+import com.google.gson.JsonObject;
+
+/**
+ * Every write command records whether it finished (SPEC.md section 9).
+ *
+ * A live management server showed six AI events and all six read
+ * `Scheduled`: an operator saw work start and never learned whether it
+ * succeeded. The obvious patch — `@ActionEvent` on the command's own
+ * `execute()` — cannot work, and was measured not working on a real
+ * server before these tests were written.
+ *
+ * `ActionEventInterceptor` is a Spring AOP advisor, so it wraps *beans*,
+ * and a command is not one: `ComponentContext.inject` calls
+ * `autowireBean` and hands back the same instance, never a proxy. The
+ * annotation therefore belongs on the manager, which is a bean — the
+ * same arrangement CloudStack uses for its own commands.
+ *
+ * The second half is as easy to get wrong: on a proxied method
+ * `eventType = ""` still records nothing, because `interceptComplete`
+ * returns early on an empty type and the fallback it would otherwise
+ * use, `ctx.getEventType()`, is never populated by the API path. So the
+ * recorder stamps the context itself, inside the proxied call, where
+ * `interceptComplete` and `interceptException` both read it afterwards.
+ */
+class EventRecordingTest {
+
+ private static final CallerContext CALLER =
+ new CallerContext("u", "acme", "/Customers/Acme", "User");
+
+ /** What the fake recorder was asked to record. */
+ private static final class Recorded {
+ final List types = new ArrayList<>();
+ final List descriptions = new ArrayList<>();
+ int runs;
+ }
+
+ private static final class TestWriteCmd extends AiServicesSyncCmd {
+ boolean succeeded;
+
+ @Override
+ protected String enginePath() {
+ return "/v1/profiles/guardrail";
+ }
+
+ @Override
+ protected String engineMethod() {
+ return "POST";
+ }
+
+ @Override
+ protected void onSuccess(JsonObject body) {
+ this.succeeded = true;
+ }
+
+ @Override
+ public String getEventType() {
+ return "AI.PROFILE.UPDATE";
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "creating guardrail profile acme";
+ }
+ }
+
+ private static final class TestListCmd extends AiServicesListCmd {
+ @Override
+ protected String enginePath() {
+ return "/v1/models";
+ }
+
+ @Override
+ protected String itemsKey() {
+ return "models";
+ }
+
+ @Override
+ protected AiModelResponse mapItem(JsonObject item) {
+ return AiModelResponse.from(item);
+ }
+ }
+
+ private static final class TestAsyncCmd extends AiServicesAsyncCmd {
+ EngineJob finished;
+
+ @Override
+ protected String enginePath() {
+ return "/v1/deployments";
+ }
+
+ @Override
+ protected void onSuccess(EngineJob job) {
+ this.finished = job;
+ }
+
+ @Override
+ public String getEventType() {
+ return "AI.MODEL.DEPLOY";
+ }
+
+ @Override
+ public String getEventDescription() {
+ return "deploying model llama";
+ }
+ }
+
+ private static AiServicesService serviceOver(
+ List answers, Recorded recorded) {
+ List remaining = new ArrayList<>(answers);
+ EngineTransport transport = (method, url, headers, body) ->
+ remaining.isEmpty() ? answers.get(answers.size() - 1) : remaining.remove(0);
+
+ AiServicesService service = mock(AiServicesService.class);
+ when(service.getEngineClient()).thenReturn(
+ new EngineClient(Collections.singletonList("https://engine"), transport));
+ when(service.currentCaller()).thenReturn(CALLER);
+ doAnswer(invocation -> {
+ recorded.types.add(invocation.getArgument(0));
+ recorded.descriptions.add(invocation.getArgument(1));
+ recorded.runs++;
+ ((Runnable) invocation.getArgument(2)).run();
+ return null;
+ }).when(service).recordEvent(anyString(), anyString(), any(Runnable.class));
+ return service;
+ }
+
+ private static T wire(T command, Class> base, AiServicesService service)
+ throws Exception {
+ Field field = base.getDeclaredField("aiServices");
+ field.setAccessible(true);
+ field.set(command, service);
+ return command;
+ }
+
+ @Test
+ void theRecorderOnTheManagerCarriesAnActionEvent() throws Exception {
+ // The annotation has to sit on the bean's method, because that
+ // is the only thing Spring proxies. Putting it on a command's
+ // execute() compiles, deploys and records nothing.
+ Method recorder = AiServicesManagerImpl.class.getMethod(
+ "recordEvent", String.class, String.class, Runnable.class);
+ ActionEvent annotation = recorder.getAnnotation(ActionEvent.class);
+
+ assertNotNull(annotation, "recordEvent must carry @ActionEvent");
+ assertFalse(annotation.async(),
+ "async = true would publish a second Scheduled event beside "
+ + "the one ApiServer already created");
+ assertEquals("", annotation.eventType(),
+ "the type comes from the CallContext, per command");
+ }
+
+ @Test
+ void aSyncWriteRoutesItsWorkThroughTheRecorder() throws Exception {
+ Recorded recorded = new Recorded();
+ TestWriteCmd command = wire(new TestWriteCmd(), AiServicesSyncCmd.class,
+ serviceOver(Collections.singletonList(
+ new EngineResponse(200, "{\"id\": \"g-1\"}")), recorded));
+
+ command.execute();
+
+ assertTrue(command.succeeded, "the work still runs");
+ assertEquals(1, recorded.runs);
+ assertEquals("AI.PROFILE.UPDATE", recorded.types.get(0));
+ assertEquals("creating guardrail profile acme", recorded.descriptions.get(0));
+ }
+
+ @Test
+ void anAsyncCommandRoutesItsWorkThroughTheRecorder() throws Exception {
+ Recorded recorded = new Recorded();
+ TestAsyncCmd command = wire(new TestAsyncCmd(), AiServicesAsyncCmd.class,
+ serviceOver(Arrays.asList(
+ new EngineResponse(202, "{\"jobid\": \"j-1\"}"),
+ new EngineResponse(200,
+ "{\"jobid\": \"j-1\", \"jobstatus\": 1,"
+ + " \"jobresult\": {\"deployment\": {}}}")),
+ recorded));
+
+ command.execute();
+
+ assertNotNull(command.finished);
+ assertEquals(1, recorded.runs);
+ assertEquals("AI.MODEL.DEPLOY", recorded.types.get(0));
+ }
+
+ @Test
+ void aListCommandRecordsNothing() throws Exception {
+ // Reads are not events. A list command declares no event type,
+ // and that absence is what keeps it out of the operator's log.
+ Recorded recorded = new Recorded();
+ TestListCmd command = wire(new TestListCmd(), AiServicesSyncCmd.class,
+ serviceOver(Collections.singletonList(new EngineResponse(200,
+ "{\"count\": 1, \"models\": [{\"name\": \"a\"}]}")), recorded));
+
+ command.execute();
+
+ assertNull(command.getEventType());
+ assertEquals(0, recorded.runs);
+ }
+
+ @Test
+ void aFailedWriteStillReachesTheRecorder() throws Exception {
+ // This is the half that matters most: the interceptor records
+ // Failed from interceptException, which only runs if the work
+ // threw *inside* the recorded call. A command that failed
+ // before reaching it would stay at Scheduled forever.
+ Recorded recorded = new Recorded();
+ TestWriteCmd command = wire(new TestWriteCmd(), AiServicesSyncCmd.class,
+ serviceOver(Collections.singletonList(
+ new EngineResponse(422, "{\"detail\": \"no such preset\"}")),
+ recorded));
+
+ assertThrows(ServerApiException.class, command::execute);
+
+ assertEquals(1, recorded.runs, "the failure happened inside the recorder");
+ assertFalse(command.succeeded);
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/PrivateEndpointNetworkTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/PrivateEndpointNetworkTest.java
new file mode 100644
index 000000000000..d73eb4ba6dff
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/command/PrivateEndpointNetworkTest.java
@@ -0,0 +1,129 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.command;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Field;
+
+import org.apache.cloudstack.api.ApiConstants;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.NetworkResponse;
+import org.junit.jupiter.api.Test;
+
+import com.cloud.exception.InvalidParameterValueException;
+import com.cloud.network.Network;
+import com.cloud.utils.db.EntityManager;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+
+/**
+ * The network a private endpoint attaches to (SPEC.md section 8).
+ *
+ *
The parameter was a plain {@code STRING}, so CloudStack never
+ * checked that the caller could see the network it named: no entity
+ * type meant no ACL check and no resolution. Declaring it a
+ * {@code UUID} with {@code entityType} gets both.
+ *
+ *
That changes what the command holds. CloudStack resolves a UUID
+ * parameter to the **internal numeric id**, and the engine stores the
+ * network id it is given and compares it against the UUIDs CloudStack
+ * returns from {@code listNetworks}. So the id has to be translated
+ * back before it is sent on, or a private endpoint would be recorded
+ * against a number that matches nothing.
+ */
+class PrivateEndpointNetworkTest {
+
+ private static void set(Object target, String field, Object value) throws Exception {
+ Field f = target.getClass().getDeclaredField(field);
+ f.setAccessible(true);
+ f.set(target, value);
+ }
+
+ private static Parameter parameterOn(Class> cls, String field) throws Exception {
+ return cls.getDeclaredField(field).getAnnotation(Parameter.class);
+ }
+
+ @Test
+ void theNetworkIsDeclaredAsAnEntitySoCloudStackChecksAccess() throws Exception {
+ Parameter annotation = parameterOn(CreateAiPrivateEndpointCmd.class, "networkId");
+
+ assertEquals(NetworkResponse.class, annotation.entityType()[0]);
+ }
+
+ @Test
+ void itIsAUuidParameterRatherThanAString() throws Exception {
+ Parameter annotation = parameterOn(CreateAiPrivateEndpointCmd.class, "networkId");
+
+ assertEquals("uuid", annotation.type().name().toLowerCase());
+ }
+
+ @Test
+ void theBodyCarriesTheNetworksUuidNotItsInternalId() throws Exception {
+ // The engine compares this against listNetworks output.
+ Network network = mock(Network.class);
+ when(network.getUuid()).thenReturn("8f1c-net-uuid");
+ EntityManager entities = mock(EntityManager.class);
+ when(entities.findById(eq(Network.class), eq(7L))).thenReturn(network);
+
+ CreateAiPrivateEndpointCmd command = new CreateAiPrivateEndpointCmd();
+ command._entityMgr = entities;
+ set(command, "deployment", "llama-prod");
+ set(command, "networkId", 7L);
+
+ JsonObject body = JsonParser.parseString(command.engineBody()).getAsJsonObject();
+
+ assertEquals("8f1c-net-uuid", body.get("network_id").getAsString());
+ }
+
+ @Test
+ void aNetworkThatCannotBeResolvedIsRefused() throws Exception {
+ EntityManager entities = mock(EntityManager.class);
+ when(entities.findById(eq(Network.class), eq(7L))).thenReturn(null);
+
+ CreateAiPrivateEndpointCmd command = new CreateAiPrivateEndpointCmd();
+ command._entityMgr = entities;
+ set(command, "deployment", "llama-prod");
+ set(command, "networkId", 7L);
+
+ assertThrows(InvalidParameterValueException.class, command::engineBody);
+ }
+
+ @Test
+ void anUnsetNetworkIsOmittedRatherThanResolved() throws Exception {
+ // A public-only endpoint names no network, and resolving null
+ // would refuse a legitimate request.
+ CreateAiPrivateEndpointCmd command = new CreateAiPrivateEndpointCmd();
+ set(command, "deployment", "llama-prod");
+
+ JsonObject body = JsonParser.parseString(command.engineBody()).getAsJsonObject();
+
+ assertFalse(body.has("network_id"));
+ }
+
+ @Test
+ void theParameterIsStillCalledNetworkid() throws Exception {
+ // CloudMonkey, Terraform and the UI all name it; renaming it
+ // while typing it would be a breaking change in disguise.
+ Parameter annotation = parameterOn(CreateAiPrivateEndpointCmd.class, "networkId");
+
+ assertEquals(ApiConstants.NETWORK_ID, annotation.name());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponseTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponseTest.java
new file mode 100644
index 000000000000..7e68f9be0348
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiApiKeyResponseTest.java
@@ -0,0 +1,69 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.response;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import org.junit.jupiter.api.Test;
+
+import com.google.gson.JsonObject;
+
+/**
+ * The one moment an API key's secret exists.
+ *
+ * The engine returns it as `apikey`, with a warning saying it cannot
+ * be retrieved again. This class read `secret`, so it was always null
+ * — a tenant could create keys and never learn any of them, through
+ * CloudMonkey, Terraform or the UI alike. A live 4.23.0.0 answered
+ * `createAiApiKey` with `{"id": …, "name": …}` and nothing else.
+ */
+class AiApiKeyResponseTest {
+
+ private static JsonObject minted() {
+ JsonObject body = new JsonObject();
+ body.addProperty("id", "884f7894b5e58aa6");
+ body.addProperty("name", "tf-probe");
+ body.addProperty("apikey", "sk-live-not-a-real-key");
+ body.addProperty("warning", "This key is shown once and cannot be retrieved again.");
+ return body;
+ }
+
+ @Test
+ void theSecretSurvivesTheOnlyMomentItExists() {
+ AiApiKeyResponse mapped = AiApiKeyResponse.from(minted());
+
+ assertEquals("sk-live-not-a-real-key", mapped.getApiKey());
+ }
+
+ @Test
+ void theIdentityComesThroughWithIt() {
+ AiApiKeyResponse mapped = AiApiKeyResponse.from(minted());
+
+ assertEquals("884f7894b5e58aa6", mapped.getId());
+ assertEquals("tf-probe", mapped.getName());
+ }
+
+ @Test
+ void aListedKeyHasNoSecretAndSaysSo() {
+ // `listAiApiKeys` returns metadata only; nothing should
+ // invent an empty string where there is no secret.
+ JsonObject listed = new JsonObject();
+ listed.addProperty("id", "884f7894b5e58aa6");
+ listed.addProperty("name", "tf-probe");
+
+ assertNull(AiApiKeyResponse.from(listed).getApiKey());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiModelResponseTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiModelResponseTest.java
new file mode 100644
index 000000000000..46f063ebb736
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/api/response/AiModelResponseTest.java
@@ -0,0 +1,120 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.api.response;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Translating the engine's catalog into CloudStack responses.
+ *
+ * The engine speaks snake_case JSON and CloudStack responses are
+ * lowercase-concatenated, so this mapping is exactly where a field goes
+ * quietly missing.
+ */
+class AiModelResponseTest {
+
+ /** Map every entry of a catalog body, as the list command does. */
+ private static List mapAll(String body) {
+ List mapped = new java.util.ArrayList<>();
+ com.google.gson.JsonObject root =
+ com.google.gson.JsonParser.parseString(body).getAsJsonObject();
+ if (root.has("models")) {
+ for (com.google.gson.JsonElement element : root.getAsJsonArray("models")) {
+ mapped.add(AiModelResponse.from(element.getAsJsonObject()));
+ }
+ }
+ return mapped;
+ }
+
+ private static final String CATALOG =
+ "{\"count\": 2, \"models\": ["
+ + "{\"name\": \"llama-3.3-70b-instruct\", \"task\": \"chat\","
+ + " \"engine\": \"vllm\", \"license\": \"llama3.3\","
+ + " \"price_tier\": \"standard\", \"max_model_len\": 32768,"
+ + " \"mirrored\": true},"
+ + "{\"name\": \"bge-m3-embedding\", \"task\": \"embedding\","
+ + " \"engine\": \"vllm\", \"license\": \"mit\","
+ + " \"price_tier\": \"embedding\", \"max_model_len\": 8192,"
+ + " \"mirrored\": false}"
+ + "]}";
+
+ @Test
+ void everyModelIsMapped() {
+ List models = mapAll(CATALOG);
+
+ assertEquals(2, models.size());
+ assertEquals("llama-3.3-70b-instruct", models.get(0).getName());
+ }
+
+ @Test
+ void theMirroredFlagSurvives() {
+ // A tenant needs to know a model cannot be deployed yet.
+ List models = mapAll(CATALOG);
+
+ assertTrue(models.get(0).getMirrored());
+ assertFalse(models.get(1).getMirrored());
+ }
+
+ @Test
+ void anEmptyCatalogIsNotAnError() {
+ assertEquals(0, mapAll("{\"count\": 0, \"models\": []}").size());
+ }
+
+ @Test
+ void aBodyWithoutModelsYieldsNothing() {
+ assertEquals(0, mapAll("{\"count\": 0}").size());
+ }
+
+ @Test
+ void aMissingOptionalFieldIsNullNotAnError() {
+ List models =
+ mapAll("{\"models\": [{\"name\": \"m\"}]}");
+
+ assertEquals("m", models.get(0).getName());
+ assertFalse(models.get(0).getMirrored());
+ }
+
+ @Test
+ void anExplicitNullIsTreatedAsAbsent() {
+ List models = mapAll(
+ "{\"models\": [{\"name\": \"m\", \"price_tier\": null,"
+ + " \"max_model_len\": null}]}");
+
+ assertEquals(1, models.size());
+ assertEquals("m", models.get(0).getName());
+ }
+
+ @Test
+ void everyEntryIsNamedForTheResponseSerialiser() {
+ for (AiModelResponse model : mapAll(CATALOG)) {
+ assertEquals("aimodel", model.getObjectName());
+ }
+ }
+
+ @Test
+ void anUnsetMaxModelLenStaysUnset() {
+ List models =
+ mapAll("{\"models\": [{\"name\": \"m\"}]}");
+
+ assertNull(models.get(0).getObjectId());
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/CallerContextTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/CallerContextTest.java
new file mode 100644
index 000000000000..915161ed2649
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/CallerContextTest.java
@@ -0,0 +1,97 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+/**
+ * The caller context the engine filters every response by
+ * (SPEC.md section 10).
+ */
+class CallerContextTest {
+
+ @Test
+ void rendersTheFourHeadersTheEngineExpects() {
+ Map headers =
+ new CallerContext("u-1", "acme", "/Customers/Acme", "User").asHeaders();
+
+ assertEquals(4, headers.size());
+ assertEquals("u-1", headers.get("X-Aisvc-User-Id"));
+ assertEquals("acme", headers.get("X-Aisvc-Account"));
+ assertEquals("/Customers/Acme", headers.get("X-Aisvc-Domain"));
+ assertEquals("User", headers.get("X-Aisvc-Role"));
+ }
+
+ @ParameterizedTest
+ @CsvSource({
+ ",acme,/d,User",
+ "u-1,,/d,User",
+ "u-1,acme,,User",
+ "u-1,acme,/d,",
+ "' ',acme,/d,User",
+ })
+ void refusesAnIncompleteContext(
+ String user, String account, String domain, String role) {
+ // The engine trusts this assertion, so a half-built one must not
+ // reach it: a blank domain would widen rather than narrow access.
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> new CallerContext(user, account, domain, role));
+ }
+
+ @Test
+ void theFailureNamesTheMissingField() {
+ IllegalArgumentException failure = assertThrows(
+ IllegalArgumentException.class,
+ () -> new CallerContext("u-1", "acme", null, "User"));
+
+ assertTrue(failure.getMessage().contains("domainPath"));
+ }
+
+ @Test
+ void equalContextsCompareEqual() {
+ assertEquals(
+ new CallerContext("u-1", "acme", "/d", "User"),
+ new CallerContext("u-1", "acme", "/d", "User"));
+ }
+
+ @Test
+ void adifferentAccountIsADifferentContext() {
+ assertNotEquals(
+ new CallerContext("u-1", "acme", "/d", "User"),
+ new CallerContext("u-1", "other", "/d", "User"));
+ }
+
+ @Test
+ void headerOrderIsStable() {
+ Map headers =
+ new CallerContext("u", "a", "/d", "User").asHeaders();
+
+ assertEquals(
+ java.util.Arrays.asList(
+ "X-Aisvc-User-Id", "X-Aisvc-Account",
+ "X-Aisvc-Domain", "X-Aisvc-Role"),
+ new java.util.ArrayList<>(headers.keySet()));
+ }
+}
diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineClientTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineClientTest.java
new file mode 100644
index 000000000000..4905078a2cdf
--- /dev/null
+++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineClientTest.java
@@ -0,0 +1,219 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with this
+// work for additional information regarding copyright ownership. The ASF
+// licenses this file to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance with the
+// License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.ai.engine;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Failover and caller context (SPEC.md sections 7 and 10).
+ *
+ * "The Java plugin accepts multiple engine URLs and fails over between
+ * them" — the rule being that only an unreachable replica is worth
+ * retrying elsewhere.
+ */
+class EngineClientTest {
+
+ private static final CallerContext CALLER =
+ new CallerContext("u-1", "acme", "/Customers/Acme", "User");
+
+ /** Records every call and answers from a script. */
+ private static final class RecordingTransport implements EngineTransport {
+ final List urls = new ArrayList<>();
+ final List