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.cloudstack cloud-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: + * + *

+ * + * 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> headers = new ArrayList<>(); + final Map answers; + final List unreachable; + + RecordingTransport(Map answers, List unreachable) { + this.answers = answers; + this.unreachable = unreachable; + } + + @Override + public EngineResponse send( + String method, String url, Map requestHeaders, String body) { + urls.add(url); + headers.add(requestHeaders); + for (String prefix : unreachable) { + if (url.startsWith(prefix)) { + throw new EngineException("connection refused to " + url); + } + } + EngineResponse answer = answers.get(url); + return answer == null ? new EngineResponse(200, "{}") : answer; + } + } + + private static RecordingTransport reachable() { + return new RecordingTransport(Collections.emptyMap(), Collections.emptyList()); + } + + @Test + void parsesACommaSeparatedSetting() { + List urls = EngineClient.parseUrls( + "https://a.internal:8443, https://b.internal:8443/ ,"); + + assertEquals(Arrays.asList("https://a.internal:8443", "https://b.internal:8443"), urls); + } + + @Test + void parsingNullYieldsNoUrls() { + assertTrue(EngineClient.parseUrls(null).isEmpty()); + } + + @Test + void refusesToBuildWithoutAnyUrl() { + IllegalArgumentException failure = assertThrows( + IllegalArgumentException.class, + () -> new EngineClient(Collections.emptyList(), reachable())); + + assertTrue(failure.getMessage().contains("ai.services.engine.urls")); + } + + @Test + void blankUrlsAreIgnored() { + EngineClient client = new EngineClient( + Arrays.asList("", " ", "https://a.internal"), reachable()); + + assertEquals(Collections.singletonList("https://a.internal"), client.getBaseUrls()); + } + + @Test + void callsTheFirstReplica() { + RecordingTransport transport = reachable(); + EngineClient client = new EngineClient( + Arrays.asList("https://a.internal", "https://b.internal"), transport); + + client.get("/v1/models", CALLER); + + assertEquals(Collections.singletonList("https://a.internal/v1/models"), transport.urls); + } + + @Test + void failsOverWhenTheFirstReplicaCannotBeReached() { + RecordingTransport transport = new RecordingTransport( + Collections.emptyMap(), Collections.singletonList("https://a.internal")); + EngineClient client = new EngineClient( + Arrays.asList("https://a.internal", "https://b.internal"), transport); + + EngineResponse answer = client.get("/v1/models", CALLER); + + assertTrue(answer.isSuccess()); + assertEquals( + Arrays.asList("https://a.internal/v1/models", "https://b.internal/v1/models"), + transport.urls); + } + + @Test + void anAnsweringReplicaIsNotRetriedElsewhere() { + // Retrying a POST against the next replica could do the work twice. + RecordingTransport transport = new RecordingTransport( + Collections.singletonMap( + "https://a.internal/v1/deployments", new EngineResponse(500, "boom")), + Collections.emptyList()); + EngineClient client = new EngineClient( + Arrays.asList("https://a.internal", "https://b.internal"), transport); + + EngineResponse answer = client.post("/v1/deployments", CALLER, "{}"); + + assertEquals(500, answer.getStatusCode()); + assertEquals(1, transport.urls.size()); + } + + @Test + void anEngineErrorFromAReachableReplicaPropagates() { + EngineTransport failing = (method, url, headers, body) -> { + throw new EngineException("forbidden", 403, "forbidden"); + }; + EngineClient client = new EngineClient( + Arrays.asList("https://a.internal", "https://b.internal"), failing); + + EngineException failure = assertThrows( + EngineException.class, () -> client.get("/v1/runs", CALLER)); + + assertEquals(403, failure.getStatusCode()); + } + + @Test + void everyReplicaUnreachableIsReportedOnce() { + RecordingTransport transport = new RecordingTransport( + Collections.emptyMap(), Arrays.asList("https://a.internal", "https://b.internal")); + EngineClient client = new EngineClient( + Arrays.asList("https://a.internal", "https://b.internal"), transport); + + EngineException failure = assertThrows( + EngineException.class, () -> client.get("/v1/models", CALLER)); + + assertTrue(failure.isUnreachable()); + assertTrue(failure.getMessage().contains("tried 2")); + assertEquals(2, transport.urls.size()); + } + + @Test + void everyRequestCarriesTheCallerContext() { + RecordingTransport transport = reachable(); + EngineClient client = + new EngineClient(Collections.singletonList("https://a.internal"), transport); + + client.get("/v1/models", CALLER); + + Map sent = transport.headers.get(0); + assertEquals("u-1", sent.get(CallerContext.USER_HEADER)); + assertEquals("acme", sent.get(CallerContext.ACCOUNT_HEADER)); + assertEquals("/Customers/Acme", sent.get(CallerContext.DOMAIN_HEADER)); + assertEquals("User", sent.get(CallerContext.ROLE_HEADER)); + } + + @Test + void trailingSlashesDoNotDoubleUp() { + RecordingTransport transport = reachable(); + EngineClient client = + new EngineClient(Collections.singletonList("https://a.internal/"), transport); + + client.get("/v1/models", CALLER); + + assertEquals("https://a.internal/v1/models", transport.urls.get(0)); + } + + @Test + void everyVerbReachesTheTransport() { + RecordingTransport transport = reachable(); + EngineClient client = + new EngineClient(Collections.singletonList("https://a.internal"), transport); + + client.get("/v1/a", CALLER); + client.post("/v1/b", CALLER, "{}"); + client.patch("/v1/c", CALLER, "{}"); + client.delete("/v1/d", CALLER); + + assertEquals(4, transport.urls.size()); + } + + @Test + void acceptedIsRecognisedForAsyncCommands() { + assertTrue(new EngineResponse(202, "{\"jobid\":\"x\"}").isAccepted()); + assertFalse(new EngineResponse(200, "{}").isAccepted()); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobPollerTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobPollerTest.java new file mode 100644 index 000000000000..fa5e4b7d9a63 --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobPollerTest.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. +package org.apache.cloudstack.ai.engine; + +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 java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.atomic.AtomicLong; + +import org.junit.jupiter.api.Test; + +/** + * Waiting on an engine job (SPEC.md sections 9 and 10). + * + * Driven with a fake clock and sleeper, so the poll loop is exercised + * without any real time passing. + */ +class EngineJobPollerTest { + + private static final CallerContext CALLER = + new CallerContext("u-1", "acme", "/Customers/Acme", "Admin"); + + private final AtomicLong now = new AtomicLong(0); + private final List sleeps = new ArrayList<>(); + + private EngineJobPoller pollerOver(List bodies, long timeoutMillis) { + List remaining = new ArrayList<>(bodies); + EngineTransport transport = (method, url, headers, body) -> { + String next = remaining.isEmpty() + ? bodies.get(bodies.size() - 1) + : remaining.remove(0); + return new EngineResponse(200, next); + }; + EngineClient client = + new EngineClient(Collections.singletonList("https://engine"), transport); + return new EngineJobPoller( + client, + 100L, + timeoutMillis, + millis -> { + sleeps.add(millis); + now.addAndGet(millis); + }, + now::get); + } + + private static String pending(String id) { + return "{\"jobid\": \"" + id + "\", \"jobstatus\": 0}"; + } + + private static String succeeded(String id) { + return "{\"jobid\": \"" + id + "\", \"jobstatus\": 1," + + " \"jobresult\": {\"deployment\": {\"id\": \"d-1\"}}}"; + } + + private static String failed(String id) { + return "{\"jobid\": \"" + id + "\", \"jobstatus\": 2," + + " \"jobresult\": {\"errortext\": \"Insufficient capacity\"," + + " \"errorcode\": 533}}"; + } + + @Test + void anAlreadyFinishedJobReturnsWithoutSleeping() { + EngineJob job = pollerOver( + Collections.singletonList(succeeded("j-1")), 10_000L).await("j-1", CALLER); + + assertTrue(job.isSuccess()); + assertTrue(sleeps.isEmpty()); + } + + @Test + void itPollsUntilTheJobFinishes() { + EngineJobPoller poller = pollerOver( + java.util.Arrays.asList(pending("j-1"), pending("j-1"), succeeded("j-1")), + 10_000L); + + EngineJob job = poller.await("j-1", CALLER); + + assertTrue(job.isSuccess()); + assertEquals(2, sleeps.size()); + } + + @Test + void theResultIsCarriedBack() { + EngineJob job = pollerOver( + Collections.singletonList(succeeded("j-1")), 10_000L).await("j-1", CALLER); + + assertEquals("d-1", + job.getResult().getAsJsonObject("deployment").get("id").getAsString()); + } + + @Test + void aFailedJobRaisesItsErrorText() { + EngineJobPoller poller = + pollerOver(Collections.singletonList(failed("j-1")), 10_000L); + + EngineException failure = + assertThrows(EngineException.class, () -> poller.await("j-1", CALLER)); + + assertEquals("Insufficient capacity", failure.getMessage()); + assertEquals(533, failure.getStatusCode()); + } + + @Test + void aTimeoutIsNotReportedAsSuccess() { + // The work may still be running; calling it done is a lie the + // operator would act on. + EngineJobPoller poller = + pollerOver(Collections.singletonList(pending("j-1")), 250L); + + EngineException failure = + assertThrows(EngineException.class, () -> poller.await("j-1", CALLER)); + + assertTrue(failure.getMessage().contains("did not finish")); + assertTrue(failure.getMessage().contains("may still be running")); + } + + @Test + void anUnreadableJobResponseIsAnError() { + EngineJobPoller poller = + pollerOver(Collections.singletonList("not json"), 10_000L); + + assertThrows(EngineException.class, () -> poller.await("j-1", CALLER)); + } + + @Test + void aNonSuccessStatusFromTheJobEndpointIsAnError() { + EngineTransport transport = + (method, url, headers, body) -> new EngineResponse(404, "{}"); + EngineClient client = + new EngineClient(Collections.singletonList("https://engine"), transport); + EngineJobPoller poller = new EngineJobPoller(client, 1000L); + + EngineException failure = + assertThrows(EngineException.class, () -> poller.await("j-1", CALLER)); + + assertTrue(failure.getMessage().contains("could not read engine job")); + assertEquals(404, failure.getStatusCode()); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobTest.java new file mode 100644 index 000000000000..720a473c56da --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/EngineJobTest.java @@ -0,0 +1,115 @@ +// 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.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import org.junit.jupiter.api.Test; + +/** + * Parsing engine jobs (SPEC.md section 10). + * + * The engine uses CloudStack's own status values deliberately, so these + * assertions are really about that contract holding. + */ +class EngineJobTest { + + @Test + void statusZeroIsPending() { + EngineJob job = EngineJob.parse("{\"jobid\": \"j-1\", \"jobstatus\": 0}"); + + assertTrue(job.isPending()); + assertFalse(job.isSuccess()); + assertEquals(EngineJob.PENDING, job.getStatus()); + } + + @Test + void statusOneIsSuccess() { + EngineJob job = EngineJob.parse( + "{\"jobid\": \"j-1\", \"jobstatus\": 1, \"jobresult\": {\"ok\": true}}"); + + assertTrue(job.isSuccess()); + assertTrue(job.getResult().get("ok").getAsBoolean()); + } + + @Test + void statusTwoIsFailureWithItsText() { + EngineJob job = EngineJob.parse( + "{\"jobid\": \"j-1\", \"jobstatus\": 2, \"jobresult\":" + + " {\"errortext\": \"nope\", \"errorcode\": 530}}"); + + assertTrue(job.isFailure()); + assertEquals("nope", job.getErrorText()); + assertEquals(530, job.getErrorCode()); + } + + @Test + void aFailureWithoutDetailStillSaysSomething() { + EngineJob job = EngineJob.parse( + "{\"jobid\": \"j-1\", \"jobstatus\": 2, \"jobresult\": {}}"); + + assertTrue(job.getErrorText().contains("no detail")); + assertNull(job.getErrorCode()); + } + + @Test + void theJobIdIsCarried() { + assertEquals("abc-123", + EngineJob.parse("{\"jobid\": \"abc-123\", \"jobstatus\": 0}").getJobId()); + } + + @Test + void theAcceptedBodyOfAnAsyncCommandParses() { + // A 202 carries only the job id; status defaults to pending. + EngineJob job = EngineJob.parse("{\"jobid\": \"j-9\"}"); + + assertEquals("j-9", job.getJobId()); + assertTrue(job.isPending()); + } + + @Test + void aBodyWithoutAJobIdIsAnError() { + EngineException failure = assertThrows( + EngineException.class, () -> EngineJob.parse("{\"jobstatus\": 1}")); + + assertTrue(failure.getMessage().contains("no job id")); + } + + @Test + void anEmptyJobIdIsAnError() { + assertThrows(EngineException.class, + () -> EngineJob.parse("{\"jobid\": \"\", \"jobstatus\": 1}")); + } + + @Test + void unparseableJsonIsAnError() { + EngineException failure = assertThrows( + EngineException.class, () -> EngineJob.parse("nope")); + + assertTrue(failure.getMessage().contains("unreadable")); + } + + @Test + void aSuccessWithNoResultIsStillASuccess() { + EngineJob job = EngineJob.parse("{\"jobid\": \"j-1\", \"jobstatus\": 1}"); + + assertTrue(job.isSuccess()); + assertNull(job.getResult()); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/HttpEngineTransportTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/HttpEngineTransportTest.java new file mode 100644 index 000000000000..f3a2d23d659c --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/HttpEngineTransportTest.java @@ -0,0 +1,218 @@ +// 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.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.io.OutputStream; +import java.net.InetSocketAddress; +import java.net.http.HttpClient; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.concurrent.atomic.AtomicInteger; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import com.sun.net.httpserver.Headers; +import com.sun.net.httpserver.HttpExchange; +import com.sun.net.httpserver.HttpServer; + +/** + * The HTTP transport, against a real socket. + * + * Driven over plain HTTP with the JDK's own server: mTLS is configured in + * {@link MutualTls} and tested there, while what matters here is that the + * request is built correctly and that an unreachable replica raises the + * unreachable form of {@link EngineException} — which is the only thing + * {@link EngineClient} fails over on. + */ +class HttpEngineTransportTest { + + private HttpServer server; + private HttpEngineTransport transport; + private final List methods = new ArrayList<>(); + private final List paths = new ArrayList<>(); + private final List headers = new ArrayList<>(); + private final List bodies = new ArrayList<>(); + private final AtomicInteger status = new AtomicInteger(200); + private String responseBody = "{\"ok\": true}"; + + @BeforeEach + void startServer() throws IOException { + server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0); + server.createContext("/", this::record); + server.start(); + transport = new HttpEngineTransport(HttpClient.newHttpClient(), Duration.ofSeconds(5)); + } + + @AfterEach + void stopServer() { + server.stop(0); + } + + private void record(HttpExchange exchange) throws IOException { + methods.add(exchange.getRequestMethod()); + paths.add(exchange.getRequestURI().getPath()); + headers.add(exchange.getRequestHeaders()); + bodies.add(new String( + exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8)); + + byte[] payload = responseBody.getBytes(StandardCharsets.UTF_8); + exchange.sendResponseHeaders(status.get(), payload.length); + try (OutputStream out = exchange.getResponseBody()) { + out.write(payload); + } + } + + private String url(String path) { + return "http://127.0.0.1:" + server.getAddress().getPort() + path; + } + + private static Map caller() { + return new CallerContext("u-1", "acme", "/Customers/Acme", "User").asHeaders(); + } + + @Test + void sendsTheMethodAndPath() { + transport.send("GET", url("/v1/models"), caller(), null); + + assertEquals("GET", methods.get(0)); + assertEquals("/v1/models", paths.get(0)); + } + + @Test + void sendsTheCallerContextHeaders() { + transport.send("GET", url("/v1/models"), caller(), null); + + assertEquals("acme", headers.get(0).getFirst(CallerContext.ACCOUNT_HEADER)); + assertEquals("User", headers.get(0).getFirst(CallerContext.ROLE_HEADER)); + } + + @Test + void returnsTheStatusAndBody() { + status.set(202); + responseBody = "{\"jobid\": \"abc\"}"; + + EngineResponse answer = transport.send("POST", url("/v1/models/mirror"), caller(), "{}"); + + assertEquals(202, answer.getStatusCode()); + assertTrue(answer.isAccepted()); + assertTrue(answer.getBody().contains("abc")); + } + + @Test + void sendsABodyWithAJsonContentType() { + transport.send("POST", url("/v1/deployments"), caller(), "{\"model\": \"m\"}"); + + assertEquals("{\"model\": \"m\"}", bodies.get(0)); + assertEquals("application/json", headers.get(0).getFirst("Content-Type")); + } + + @Test + void sendsNoContentTypeWithoutABody() { + transport.send("GET", url("/v1/models"), caller(), null); + + assertEquals(null, headers.get(0).getFirst("Content-Type")); + } + + @Test + void anErrorStatusIsReturnedRatherThanThrown() { + // The engine answered; EngineClient must not fail over for this. + status.set(503); + + EngineResponse answer = transport.send("GET", url("/v1/models"), caller(), null); + + assertEquals(503, answer.getStatusCode()); + assertTrue(!answer.isSuccess()); + } + + @Test + void anUnreachableReplicaRaisesTheUnreachableForm() { + // Port 1 on loopback refuses connections. + EngineException failure = assertThrows( + EngineException.class, + () -> transport.send("GET", "http://127.0.0.1:1/v1/models", caller(), null)); + + assertTrue(failure.isUnreachable(), "must be unreachable so the client fails over"); + assertTrue(failure.getMessage().contains("could not reach engine")); + } + + @Test + void failoverWorksEndToEndThroughTheRealTransport() { + EngineClient client = new EngineClient( + java.util.Arrays.asList( + "http://127.0.0.1:1", + "http://127.0.0.1:" + server.getAddress().getPort()), + transport); + + EngineResponse answer = client.get( + "/v1/models", new CallerContext("u", "a", "/d", "Admin")); + + assertTrue(answer.isSuccess()); + assertEquals(Collections.singletonList("/v1/models"), paths); + } + + @Test + void everyVerbReachesTheServer() { + transport.send("GET", url("/v1/a"), caller(), null); + transport.send("POST", url("/v1/b"), caller(), "{}"); + transport.send("PATCH", url("/v1/c"), caller(), "{}"); + transport.send("DELETE", url("/v1/d"), caller(), null); + + assertEquals(java.util.Arrays.asList("GET", "POST", "PATCH", "DELETE"), methods); + } + + @Test + void theTransportIsConstructibleFromConfiguredTimeouts() { + assertNotNull(new HttpEngineTransport(HttpClient.newHttpClient(), Duration.ofSeconds(1))); + } + + @Test + void anUnreachableEngineSaysSomethingWhenTheCauseWillNot() { + // Measured by killing both replicas: an operator was told + // + // no AI Services engine replica answered (tried 2): could + // not reach engine at https://…/v1/models: null + // + // because the IOException behind a refused connection can + // carry no message at all, and "null" is what that renders + // as. The class name is not much, but it is a fact about + // what happened. + IOException silent = new IOException(); + + String described = HttpEngineTransport.describe(silent); + + assertFalse(described.contains("null"), described); + assertTrue(described.contains("IOException"), described); + } + + @Test + void aCauseThatSpeaksForItselfIsLeftAlone() { + IOException refused = new IOException("Connection refused"); + + assertEquals("Connection refused", HttpEngineTransport.describe(refused)); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/MutualTlsTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/MutualTlsTest.java new file mode 100644 index 000000000000..adc97c643f96 --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/MutualTlsTest.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. +package org.apache.cloudstack.ai.engine; + +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * mTLS is mandatory (SPEC.md section 11). + * + * The engine trusts the caller context this plugin asserts. If the plugin + * ever connected without a client certificate, anything that could reach + * the engine could claim to be any tenant — so an unconfigured or broken + * setup has to fail loudly rather than fall back. + */ +class MutualTlsTest { + + @Test + void refusesWhenNoClientCertificateIsConfigured() { + EngineException failure = assertThrows( + EngineException.class, () -> MutualTls.contextFor(null, "pw", "/tmp/ca", "changeit")); + + assertTrue(failure.getMessage().contains("ai.services.engine.tls.client.cert")); + } + + @Test + void refusesWhenTheClientCertificateIsBlank() { + assertThrows( + EngineException.class, () -> MutualTls.contextFor(" ", "pw", "/tmp/ca", "changeit")); + } + + @Test + void refusesWhenNoTrustStoreIsConfigured(@TempDir Path dir) throws IOException { + Path keystore = Files.createFile(dir.resolve("client.p12")); + + EngineException failure = assertThrows( + EngineException.class, + () -> MutualTls.contextFor(keystore.toString(), "pw", "", "changeit")); + + assertTrue(failure.getMessage().contains("ai.services.engine.tls.truststore")); + } + + @Test + void refusesWhenTheCertificateFileIsMissing(@TempDir Path dir) { + EngineException failure = assertThrows( + EngineException.class, + () -> MutualTls.contextFor( + dir.resolve("absent.p12").toString(), "pw", + dir.resolve("ca.p12").toString(), "changeit")); + + assertTrue(failure.getMessage().contains("unreadable")); + } + + @Test + void reportsAnUnusableKeyStoreRatherThanConnectingAnyway(@TempDir Path dir) + throws IOException { + Path keystore = Files.write(dir.resolve("client.p12"), new byte[] {1, 2, 3}); + Path truststore = Files.write(dir.resolve("ca.p12"), new byte[] {4, 5, 6}); + + EngineException failure = assertThrows( + EngineException.class, + () -> MutualTls.contextFor( + keystore.toString(), "pw", truststore.toString(), "changeit")); + + assertTrue(failure.getMessage().contains("mTLS context")); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/TrustStoreTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/TrustStoreTest.java new file mode 100644 index 000000000000..fc65b216ddff --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/engine/TrustStoreTest.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 static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.FileOutputStream; +import java.io.OutputStream; +import java.nio.file.Path; +import java.security.KeyStore; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * The engine's CA, as the plugin reads it. + * + *

The truststore was loaded with an empty password, which no + * operator could satisfy. A PKCS12 store written by openssl with an + * empty password loads as **zero entries** rather than failing, and + * `TrustManagerFactory` then builds a trust manager that trusts + * nothing — so every call to the engine fails at the handshake with an + * error naming neither the truststore nor the CA. keytool cannot write + * an empty-password store at all: it requires six characters. + * + *

So the password is configurable, and an empty truststore is an + * error naming the file rather than a context that refuses everything. + */ +class TrustStoreTest { + + private static Path emptyStore(Path dir, String password) throws Exception { + KeyStore store = KeyStore.getInstance("PKCS12"); + store.load(null, null); + Path path = dir.resolve("empty.p12"); + try (OutputStream out = new FileOutputStream(path.toFile())) { + store.store(out, password.toCharArray()); + } + return path; + } + + @Test + void anEmptyTrustStoreIsRefusedRatherThanTrustingNothing(@TempDir Path dir) + throws Exception { + // The silent case. Without this the operator sees a handshake + // failure that says nothing about the truststore. + Path store = emptyStore(dir, "changeit"); + + EngineException thrown = assertThrows( + EngineException.class, + () -> MutualTls.contextFor( + store.toString(), "changeit", store.toString(), "changeit")); + + assertTrue(thrown.getMessage().contains("no certificates"), + thrown.getMessage()); + } + + @Test + void theTrustStorePasswordIsUsed(@TempDir Path dir) throws Exception { + // Loading with the wrong password throws before anything can + // read an entry, so the message must point at the password. + Path store = emptyStore(dir, "changeit"); + + EngineException thrown = assertThrows( + EngineException.class, + () -> MutualTls.contextFor( + store.toString(), "changeit", store.toString(), "wrong")); + + assertTrue(thrown.getMessage().toLowerCase().contains("password"), + thrown.getMessage()); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListenerTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListenerTest.java new file mode 100644 index 000000000000..7cce8b01ae30 --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/AiMaintenanceListenerTest.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.maintenance; + +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.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import org.apache.cloudstack.framework.events.Event; +import org.junit.jupiter.api.Test; + +/** + * Subscribing to host maintenance (SPEC.md section 7). + * + *

CloudStack 4.23 offers no synchronous pre-maintenance hook, so the + * event bus is the only way a plugin hears about this at all — and the + * bus is not enabled in a default install. These check both halves: that + * a maintenance event reaches the drain, and that an install with no bus + * is told so rather than quietly doing nothing. + */ +class AiMaintenanceListenerTest { + + private static final class RecordingDrain extends MaintenanceDrain { + final List hosts = new ArrayList<>(); + + RecordingDrain() { + super(hostId -> List.of(), (n, c, t) -> Outcome.DRAINED, (h, n, r) -> { + }, 900); + } + + @Override + public boolean beforeMaintenance(long hostId, org.apache.cloudstack.ai.engine.CallerContext caller) { + hosts.add(hostId); + return true; + } + } + + private Event maintenanceEvent(String entityId) { + Event event = new Event("management-server", "ActionEvent", "MAINT.PREPARE", "Host", entityId); + Map details = new HashMap<>(); + details.put("entityuuid", entityId); + event.setDescription("{\"entityuuid\":\"" + entityId + "\"}"); + return event; + } + + @Test + void aMaintenanceEventDrainsThatHost() { + RecordingDrain drain = new RecordingDrain(); + AiMaintenanceListener listener = new AiMaintenanceListener(drain, uuid -> 42L); + + listener.onEvent(maintenanceEvent("host-uuid")); + + assertEquals(List.of(42L), drain.hosts); + } + + @Test + void anUnrelatedEventIsIgnored() { + RecordingDrain drain = new RecordingDrain(); + AiMaintenanceListener listener = new AiMaintenanceListener(drain, uuid -> 42L); + + listener.onEvent(new Event("management-server", "ActionEvent", "VM.START", "VirtualMachine", "x")); + + assertTrue(drain.hosts.isEmpty()); + } + + @Test + void anEventForAnUnknownHostIsIgnored() { + // A host the plugin cannot resolve is not one it has nodes on. + RecordingDrain drain = new RecordingDrain(); + AiMaintenanceListener listener = new AiMaintenanceListener(drain, uuid -> null); + + listener.onEvent(maintenanceEvent("ghost")); + + assertTrue(drain.hosts.isEmpty()); + } + + @Test + void aFailureInTheDrainDoesNotEscapeIntoTheBus() { + // An exception thrown back at the event bus can unsubscribe the + // listener or stall other subscribers. This one logs and returns. + AiMaintenanceListener listener = new AiMaintenanceListener( + new MaintenanceDrain(hostId -> List.of("a"), (n, c, t) -> { + throw new IllegalStateException("the engine is unreachable"); + }, (h, n, r) -> { + }, 900), + uuid -> 42L); + + listener.onEvent(maintenanceEvent("host-uuid")); + } + + @Test + void theSubscribedTopicIsHostMaintenance() { + assertEquals("MAINT.PREPARE", AiMaintenanceListener.MAINTENANCE_EVENT); + assertEquals("Host", AiMaintenanceListener.HOST_CATEGORY); + } + + @Test + void theTopicFiltersToHostMaintenanceOnly() { + assertNotNull(AiMaintenanceListener.topic()); + assertEquals("Host", AiMaintenanceListener.topic().getResourceType()); + } + + @Test + void anInstallWithNoEventBusIsReportedAsInactive() { + // The whole point: without a bus this never fires, and an + // operator must be told rather than assume drains are automatic. + AiMaintenanceListener listener = new AiMaintenanceListener(new RecordingDrain(), uuid -> 42L); + + assertFalse(listener.subscribe(null)); + assertFalse(listener.isActive()); + } + + @Test + void theInactiveWarningSaysWhatToDoInstead() { + AiMaintenanceListener listener = new AiMaintenanceListener(new RecordingDrain(), uuid -> 42L); + listener.subscribe(null); + + assertTrue(listener.inactiveReason().contains("drainAiNode")); + assertTrue(listener.inactiveReason().toLowerCase().contains("event bus")); + } +} diff --git a/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrainTest.java b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrainTest.java new file mode 100644 index 000000000000..b7881d8f2673 --- /dev/null +++ b/plugins/api/ai-services/src/test/java/org/apache/cloudstack/ai/maintenance/MaintenanceDrainTest.java @@ -0,0 +1,170 @@ +// 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 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.ArrayList; +import java.util.List; + +import org.apache.cloudstack.ai.engine.CallerContext; +import org.junit.jupiter.api.Test; + +/** + * Draining GPU nodes before a host enters maintenance (SPEC.md section 7). + * + *

Passthrough GPUs cannot live-migrate (ADR-0003), so CloudStack's own + * maintenance cannot move these VMs: they have to be destroyed and + * replaced. That is what this asks the engine to do. + * + *

The decision itself — whether there is capacity elsewhere, whether a + * force is needed — belongs to the engine's {@code lifecycle} module and is + * not repeated here. This only checks the asking. + */ +class MaintenanceDrainTest { + + /** Records what the drainer was asked to do. */ + private static final class RecordingDrainer implements MaintenanceDrain.Drainer { + final List drained = new ArrayList<>(); + MaintenanceDrain.Outcome outcome = MaintenanceDrain.Outcome.DRAINED; + + @Override + public MaintenanceDrain.Outcome drain(String nodeId, CallerContext caller, int timeoutSeconds) { + drained.add(nodeId); + return outcome; + } + } + + private static final class RecordingAlerts implements MaintenanceDrain.Alerts { + final List raised = new ArrayList<>(); + + @Override + public void needsForcedDrain(long hostId, String nodeId, String reason) { + raised.add(nodeId + ": " + reason); + } + } + + private MaintenanceDrain drainFor(List nodes, RecordingDrainer drainer, RecordingAlerts alerts) { + return new MaintenanceDrain(hostId -> nodes, drainer, alerts, 900); + } + + @Test + void everyGpuNodeOnTheHostIsDrained() { + RecordingDrainer drainer = new RecordingDrainer(); + MaintenanceDrain drain = drainFor(List.of("aisvc-h100-pool-001", "aisvc-h100-pool-002"), + drainer, new RecordingAlerts()); + + drain.beforeMaintenance(42L, CallerContext.system()); + + assertEquals(List.of("aisvc-h100-pool-001", "aisvc-h100-pool-002"), drainer.drained); + } + + @Test + void aHostWithNoGpuNodesIsLeftAlone() { + RecordingDrainer drainer = new RecordingDrainer(); + MaintenanceDrain drain = drainFor(List.of(), drainer, new RecordingAlerts()); + + assertTrue(drain.beforeMaintenance(42L, CallerContext.system())); + assertTrue(drainer.drained.isEmpty()); + } + + @Test + void aSuccessfulDrainLetsMaintenanceProceed() { + MaintenanceDrain drain = drainFor(List.of("aisvc-h100-pool-001"), + new RecordingDrainer(), new RecordingAlerts()); + + assertTrue(drain.beforeMaintenance(42L, CallerContext.system())); + } + + @Test + void aDrainNeedingConfirmationStopsMaintenance() { + // SPEC.md section 7: "if capacity elsewhere is short, the admin + // must confirm a forced drain". Proceeding anyway would take the + // replicas down with no-one having agreed to it. + RecordingDrainer drainer = new RecordingDrainer(); + drainer.outcome = MaintenanceDrain.Outcome.NEEDS_FORCE; + MaintenanceDrain drain = drainFor(List.of("aisvc-h100-pool-001"), drainer, new RecordingAlerts()); + + assertFalse(drain.beforeMaintenance(42L, CallerContext.system())); + } + + @Test + void aDrainNeedingConfirmationRaisesAnAlert() { + RecordingDrainer drainer = new RecordingDrainer(); + drainer.outcome = MaintenanceDrain.Outcome.NEEDS_FORCE; + RecordingAlerts alerts = new RecordingAlerts(); + drainFor(List.of("aisvc-h100-pool-001"), drainer, alerts) + .beforeMaintenance(42L, CallerContext.system()); + + assertEquals(1, alerts.raised.size()); + assertTrue(alerts.raised.get(0).contains("aisvc-h100-pool-001")); + } + + @Test + void aTimedOutDrainStopsMaintenanceToo() { + RecordingDrainer drainer = new RecordingDrainer(); + drainer.outcome = MaintenanceDrain.Outcome.TIMED_OUT; + MaintenanceDrain drain = drainFor(List.of("aisvc-h100-pool-001"), drainer, new RecordingAlerts()); + + assertFalse(drain.beforeMaintenance(42L, CallerContext.system())); + } + + @Test + void theRestOfTheNodesAreStillAttemptedAfterOneFails() { + // Stopping at the first failure would leave the other nodes + // serving on a host that is about to go down anyway. + List attempted = new ArrayList<>(); + MaintenanceDrain drain = new MaintenanceDrain( + hostId -> List.of("a", "b", "c"), + (nodeId, caller, timeout) -> { + attempted.add(nodeId); + return nodeId.equals("a") + ? MaintenanceDrain.Outcome.TIMED_OUT + : MaintenanceDrain.Outcome.DRAINED; + }, + new RecordingAlerts(), + 900); + + drain.beforeMaintenance(42L, CallerContext.system()); + + assertEquals(List.of("a", "b", "c"), attempted); + } + + @Test + void theConfiguredTimeoutIsPassedThrough() { + List seen = new ArrayList<>(); + MaintenanceDrain drain = new MaintenanceDrain( + hostId -> List.of("a"), + (nodeId, caller, timeout) -> { + seen.add(timeout); + return MaintenanceDrain.Outcome.DRAINED; + }, + new RecordingAlerts(), + 120); + + drain.beforeMaintenance(42L, CallerContext.system()); + + assertEquals(List.of(120), seen); + } + + @Test + void theDrainActsAsTheSystemNotAsATenant() { + // Maintenance is an operator action. Asserting a tenant's context + // here would have the engine filter the reply by their account. + assertTrue(CallerContext.system().isAdmin()); + } +} diff --git a/plugins/api/ai-services/src/test/resources/generated-engine-objects.json b/plugins/api/ai-services/src/test/resources/generated-engine-objects.json new file mode 100644 index 000000000000..4a1d7a8c6a32 --- /dev/null +++ b/plugins/api/ai-services/src/test/resources/generated-engine-objects.json @@ -0,0 +1,180 @@ +{ + "AiAdapterResponse": { + "account": "sample", + "basemodel": "sample", + "created": "sample", + "id": "sample", + "name": "sample", + "rank": 7, + "servedmodelname": "sample", + "shared": true, + "sizebytes": 1234 + }, + "AiApiKeyResponse": { + "allowedmodels": "sample", + "apikey": "sample", + "expires": "sample", + "id": "sample", + "lastused": "sample", + "name": "sample" + }, + "AiBatchResponse": { + "account": "sample", + "created": "sample", + "finished": "sample", + "id": "sample", + "inputuri": "sample", + "model": "sample", + "outputuri": "sample", + "requestcount": 7, + "status": "sample" + }, + "AiBudgetResponse": { + "account": "sample", + "blocked": true, + "currency": "sample", + "domain": "sample", + "id": "sample", + "monthly": 1.5, + "on_exceed": "sample", + "percent_used": 1.5, + "spent": 1.5 + }, + "AiCertificateResponse": { + "account": "sample", + "created": "sample", + "customdomain": "sample", + "expires": "sample", + "fingerprint": "sample", + "id": "sample", + "serial": 7 + }, + "AiEffectiveParameterResponse": { + "locked": true, + "locked_at": "sample", + "name": "sample", + "policy": "sample", + "source": "sample", + "value": "sample" + }, + "AiEndpointResponse": { + "base_url": "sample", + "model": "sample", + "price_tier": "sample", + "snippets": "sample", + "task": "sample" + }, + "AiEvaluationResponse": { + "id": "sample", + "model": "sample", + "overridden": true, + "passed": true, + "revision": "sample", + "summary": "sample" + }, + "AiGpuCapacityResponse": { + "gpu_class": "sample", + "gpus_free": 7, + "gpus_total": 7, + "nodes_free": 7, + "nodes_healthy": 7, + "nodes_total": 7, + "zone": "sample" + }, + "AiGpuClassProposalResponse": { + "host_tag": "sample", + "hosts": 7, + "suggested_name": "sample" + }, + "AiGuardrailCheckResponse": { + "action": "sample", + "name": "sample", + "policy": "sample" + }, + "AiGuardrailProfileResponse": { + "checks": "sample", + "id": "sample", + "name": "sample", + "scope": "sample", + "target": "sample" + }, + "AiHfCheckResponse": { + "architecture": "sample", + "compatible": true, + "context_length": 7, + "download_bytes": 1234, + "gated": true, + "license": "sample", + "repo_id": "sample", + "requires_remote_code": true, + "revision": "sample" + }, + "AiHfModelResponse": { + "gated": true, + "license": "sample", + "repo_id": "sample", + "task": "sample" + }, + "AiPlaygroundSessionResponse": { + "apikey": "sample", + "base_url": "sample", + "expires": "sample", + "id": "sample", + "model": "sample" + }, + "AiPrivateEndpointResponse": { + "account": "sample", + "certificate": "sample", + "created": "sample", + "customdomain": "sample", + "deployment": "sample", + "exposure": "sample", + "id": "sample", + "network": "sample", + "publicenabled": true, + "tls": "sample" + }, + "AiProfileResponse": { + "id": "sample", + "kind": "sample", + "name": "sample", + "scope": "sample", + "target": "sample" + }, + "AiReconcilerActionResponse": { + "error": "sample", + "kind": "sample", + "name": "sample", + "outcome": "sample", + "resource_type": "sample" + }, + "AiReconcilerRunResponse": { + "actions": "sample", + "dry_run": true, + "finished_at": "sample", + "id": "sample", + "started_at": "sample", + "status": "sample", + "zone": "sample" + }, + "AiSetupCheckResponse": { + "detail": "sample", + "name": "sample", + "remedy": "sample", + "status": "sample" + }, + "AiSnippetResponse": { + "code": "sample", + "language": "sample", + "name": "sample" + }, + "AiUsageResponse": { + "account": "sample", + "cost": 1.5, + "currency": "sample", + "gpu_hours": 1.5, + "input_tokens": 1234, + "model": "sample", + "output_tokens": 1234 + } +} diff --git a/plugins/api/ai-services/tools/generate_commands.py b/plugins/api/ai-services/tools/generate_commands.py new file mode 100644 index 000000000000..dcd62957ffe2 --- /dev/null +++ b/plugins/api/ai-services/tools/generate_commands.py @@ -0,0 +1,2113 @@ +#!/usr/bin/env python3 +# 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. + +"""Generate the repetitive AI Services command and response classes. + +SPEC.md section 9's command map is thirty-five v1 commands that differ +only in name, verb, engine path, parameters and response shape. Writing +them out by hand invites the one transposed path or wrong role that no +reviewer would spot, so the leaves are generated from a table and the +interesting parts — the base classes, the engine client, the async +bridge — stay hand-written. + +Run from `java-plugin/`: + + python3 tools/generate_commands.py + +Generated files carry a header saying so. Edit this script, not them. +""" + +from __future__ import annotations + +import re +import sys +from dataclasses import dataclass +from pathlib import Path + +# Who may call each command comes from the engine's map rather than a +# fourth copy of it. Both modules are pure standard library, so this +# costs the generator nothing and cannot drift. +sys.path.insert(0, str(Path(__file__).resolve().parents[2])) + +from aisvc.api.commands import COMMANDS as ENGINE_COMMANDS + +ROOT = Path(__file__).resolve().parent.parent +PKG = ROOT / "src/main/java/org/apache/cloudstack/ai/api" + +LICENCE = """// 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 = """ +// GENERATED by tools/generate_commands.py from SPEC.md section 9's command +// map. Edit the generator, not this file. +""" + + +# -------------------------------------------------------------------------- +# Response types +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Field: + java: str # Java field name + wire: str # engine JSON field + api: str # CloudStack response field + type: str # String | Integer | Long | Boolean | Double + doc: str + #: Set to another response class to carry a list of them. The + #: engine sends some things that are not scalars — an endpoint's + #: snippets are objects with a name, a language and code — and a + #: response that can only hold scalars simply drops them, which is + #: how the snippets tab came to have no data source at all. + nested: str | None = None + #: The engine sends this one as a JSON *object* keyed by name rather + #: than an array — a guardrail profile's checks are + #: {"pii": {"action": …}} — so each entry becomes one nested object + #: carrying its key as `name`. Without it a map field is simply + #: dropped, which is how a locked guardrail came to be invisible on + #: the screen that sells it. + nested_map: bool = False + + +@dataclass(frozen=True) +class Response: + name: str + object_name: str + doc: str + fields: tuple[Field, ...] + + +def f( + java: str, + wire: str, + type_: str, + doc: str, + api: str | None = None, + nested: str | None = None, + nested_map: bool = False, +) -> Field: + return Field( + java=java, + wire=wire, + api=api or java.lower(), + type=type_, + doc=doc, + nested=nested, + nested_map=nested_map, + ) + + +RESPONSES: tuple[Response, ...] = ( + Response( + "AiAdapterResponse", + "aiadapter", + "A tenant's LoRA adapter (SPEC.md section 8).", + ( + f("id", "id", "String", "the adapter's id"), + f("name", "name", "String", "the adapter's name"), + f("baseModel", "basemodel", "String", "the base it is served on", "basemodel"), + f( + "servedModelName", + "servedmodelname", + "String", + "what to address it as at the gateway", + "servedmodelname", + ), + f("rank", "rank", "Integer", "its LoRA rank"), + f("sizeBytes", "sizebytes", "Long", "its size on disk", "sizebytes"), + f("account", "account", "String", "the owning account"), + f("shared", "shared", "Boolean", "whether it is shared across the domain"), + f("created", "created", "String", "when it was uploaded"), + ), + ), + Response( + "AiBatchResponse", + "aibatch", + "A batch inference job (SPEC.md section 8).", + ( + f("id", "id", "String", "the batch's id"), + f("model", "model", "String", "the model it runs against"), + f( + "status", + "status", + "String", + "validating, in_progress, completed, failed, expired or cancelled", + ), + f( + "requestCount", + "requestcount", + "Integer", + "how many requests it holds", + "requestcount", + ), + f("account", "account", "String", "the owning account"), + f("created", "created", "String", "when it was submitted"), + f("finished", "finished", "String", "when it finished, if it has"), + f("inputUri", "inputuri", "String", "where its JSONL input came from", "inputuri"), + f( + "outputUri", + "outputuri", + "String", + "where its results were written, once it has any", + "outputuri", + ), + ), + ), + Response( + "AiGuardrailProfileResponse", + "aiguardrailprofile", + "A guardrail profile and where it is bound (SPEC.md sections 6, 8).", + ( + f("id", "id", "String", "the profile's id"), + f("name", "name", "String", "the profile's name"), + f("scope", "scope", "String", "the level it is bound at"), + f("target", "target", "String", "the domain, account or deployment"), + # Keyed by check name on the engine, so `nested_map`. Without + # it the field was dropped and the guardrails screen showed a + # profile with no checks in it — the one thing it is for. + f( + "checks", + "checks", + "String", + "the checks this profile applies", + nested="AiGuardrailCheckResponse", + nested_map=True, + ), + ), + ), + Response( + "AiEvaluationResponse", + "aievaluation", + "A pre-publish evaluation verdict (SPEC.md section 8).", + ( + f("id", "id", "String", "the evaluation's id"), + f("model", "model", "String", "the model evaluated"), + f("revision", "revision", "String", "the revision evaluated"), + f("passed", "passed", "Boolean", "whether publishing is allowed"), + f("overridden", "overridden", "Boolean", "whether a root admin forced it through"), + f("summary", "summary", "String", "what the gate concluded"), + ), + ), + Response( + "AiCertificateResponse", + "aicertificate", + "An uploaded TLS certificate. Never carries the key or the " + "certificate body (SPEC.md section 8).", + ( + f("id", "id", "String", "the certificate's id"), + f("customDomain", "customdomain", "String", "the domain it covers", "customdomain"), + f("fingerprint", "fingerprint", "String", "its SHA-256 fingerprint"), + f("expires", "expires", "String", "when it expires"), + f( + "serial", + "serial", + "Integer", + "bumped on each replacement; a proxy built from an older one is stale", + ), + f("account", "account", "String", "the owning account"), + f("created", "created", "String", "when it was uploaded"), + ), + ), + Response( + "AiPrivateEndpointResponse", + "aiprivateendpoint", + "How a deployment is exposed (SPEC.md section 8).", + ( + f("id", "id", "String", "the exposure's id"), + f("deployment", "deployment", "String", "the deployment it fronts"), + f("exposure", "exposure", "String", "in words: public, private, or both"), + f("network", "network", "String", "the tier the private endpoint sits on"), + f("publicEnabled", "publicenabled", "Boolean", "whether it is also reachable publicly"), + f("customDomain", "customdomain", "String", "the domain it answers on, if any"), + f("tls", "tls", "String", "where its certificate comes from: none, acme or uploaded"), + f("certificate", "certificate", "String", "the uploaded certificate it uses, if any"), + f("account", "account", "String", "the owning account"), + f("created", "created", "String", "when it was created"), + ), + ), + Response( + "AiHfModelResponse", + "aihfmodel", + "One Hugging Face repo from a search (SPEC.md section 5).", + ( + f("repoId", "repo_id", "String", "the Hugging Face repository id", "repoid"), + f("license", "license", "String", "the repo's declared licence"), + f("task", "task", "String", "the repo's pipeline task"), + f( + "gated", + "gated", + "Boolean", + "whether the licence must be accepted on Hugging Face first", + ), + ), + ), + Response( + "AiHfCheckResponse", + "aihfcheck", + "A model compatibility report (SPEC.md section 5, step 2).", + ( + f("repoId", "repo_id", "String", "the repository checked", "repoid"), + f("revision", "revision", "String", "the commit the report is for"), + f("compatible", "compatible", "Boolean", "whether this model can be served"), + f("architecture", "architecture", "String", "the architecture from config.json"), + f("license", "license", "String", "the declared licence"), + f("downloadBytes", "download_bytes", "Long", "bytes to mirror", "downloadbytes"), + f( + "contextLength", + "context_length", + "Integer", + "the model's maximum context length", + "contextlength", + ), + f("gated", "gated", "Boolean", "whether the repo is gated"), + f( + "requiresRemoteCode", + "requires_remote_code", + "Boolean", + "whether the repo ships its own modelling code", + "requiresremotecode", + ), + ), + ), + Response( + "AiReconcilerActionResponse", + "aireconcileraction", + "One action inside a reconcile run (SPEC.md section 4).\n *\n * A failed action" + " stops only its dependants, so a run can be part\n * applied and the outcome" + " per action is what says how far it got.", + ( + f("kind", "kind", "String", "what was done: create, update, delete"), + f( + "resourceType", + "resource_type", + "String", + "the kind of thing it was done to", + "resourcetype", + ), + f("name", "name", "String", "which one"), + f("outcome", "outcome", "String", "succeeded, failed or skipped"), + f("error", "error", "String", "why it failed, where it did"), + ), + ), + Response( + "AiGuardrailCheckResponse", + "aiguardrailcheck", + "One check inside a guardrail profile (SPEC.md section 8).\n *\n * The engine" + " keys these by name, so the name comes from the key\n * rather than from the" + " object beside it. The check's own `value` —\n * a topic list, or a size in" + " characters — is not carried: it is a\n * different shape per check, and what" + " a screen needs to show is\n * which checks apply and how strictly.", + ( + f("name", "name", "String", "the check: pii, topics, input_size and so on"), + f("action", "action", "String", "what it does on a match: block, warn or allow"), + f("policy", "policy", "String", "default, clamp or locked"), + ), + ), + Response( + "AiSnippetResponse", + "aisnippet", + "A copy-ready call against one endpoint (SPEC.md section 7).\n *\n * Rendered" + ' by the engine, so there is one implementation of\n * "how you call this".' + " It reads the key from the environment\n * rather than carrying one: a snippet" + " is copied into tickets and\n * chats, where a live key would outlive any" + " session.", + ( + f("name", "name", "String", "what this snippet shows"), + f("language", "language", "String", "the language it is written in"), + f("code", "code", "String", "the snippet itself"), + ), + ), + Response( + "AiEndpointResponse", + "aiendpoint", + "One OpenAI-compatible endpoint (SPEC.md section 7).", + ( + f("model", "model", "String", "the model this endpoint serves"), + f("baseUrl", "base_url", "String", "the OpenAI-compatible base URL", "baseurl"), + f("task", "task", "String", "chat, embedding, rerank or vision-chat"), + f("priceTier", "price_tier", "String", "the price tier billed", "pricetier"), + # The snippets tab's data source. Without it the tab had + # none at all: no endpoint-facing command returned them, + # and a response that can only carry scalars could not. + f( + "snippets", + "snippets", + "String", + "copy-ready calls against this endpoint", + "snippets", + nested="AiSnippetResponse", + ), + ), + ), + Response( + "AiApiKeyResponse", + "aiapikey", + "A scoped API key (SPEC.md section 7).\n *\n * The secret appears once, on creation," + " and never again: keys are stored\n * as salted hashes.", + ( + f("id", "id", "String", "the key's identifier"), + f("name", "name", "String", "the operator's name for this key"), + # `apikey` on all three sides: the engine returns it under + # that name and CloudStack's own key APIs use it. This read + # the engine's body for `secret`, which it never sends, so + # the one moment a key's secret existed it was dropped — + # on CloudMonkey, Terraform and the UI alike. + f( + "apiKey", + "apikey", + "String", + "the key itself, returned only when it is created", + "apikey", + ), + # `listAiApiKeys` sends these already lowercase-concatenated + # while `createAiApiKey` sends snake_case, so reading the + # snake_case names left every listed key with nothing but + # an id and a name. + f( + "allowedModels", + "allowedmodels", + "String", + "models this key may use", + "allowedmodels", + ), + f("expires", "expires", "String", "when the key expires"), + f("lastUsed", "lastused", "String", "when the key was last used", "lastused"), + ), + ), + Response( + "AiProfileResponse", + "aiprofile", + "A tuning profile (SPEC.md section 6).", + ( + f("id", "id", "String", "the profile's identifier"), + f("name", "name", "String", "the profile's name"), + f("kind", "kind", "String", "serving, generation or guardrail"), + f("scope", "scope", "String", "the scope this profile is assigned at"), + f("target", "target", "String", "what the assignment applies to"), + ), + ), + Response( + "AiEffectiveParameterResponse", + "aieffectiveparameter", + "One resolved generation parameter and where it came from\n * (SPEC.md section 6).", + ( + f("name", "name", "String", "the parameter"), + f("value", "value", "String", "the value that will be applied"), + f( + "source", + "source", + "String", + "the precedence level that set it: platform, model, domain," + " account, deployment, key or request", + ), + f("policy", "policy", "String", "default, clamp or locked"), + f("locked", "locked", "Boolean", "whether a lower level may override it"), + f("lockedAt", "locked_at", "String", "the level that locked it", "lockedat"), + ), + ), + Response( + "AiUsageResponse", + "aiusage", + "Metered usage for one tenant and model (SPEC.md section 7).", + ( + f("account", "account", "String", "the account billed"), + f("model", "model", "String", "the model used"), + f("inputTokens", "input_tokens", "Long", "input tokens", "inputtokens"), + f("outputTokens", "output_tokens", "Long", "output tokens", "outputtokens"), + f("gpuHours", "gpu_hours", "Double", "GPU hours consumed", "gpuhours"), + f("cost", "cost", "Double", "spend in the tier's currency"), + f("currency", "currency", "String", "the currency of the cost"), + ), + ), + Response( + "AiBudgetResponse", + "aibudget", + "A monthly budget and where it stands (SPEC.md section 7).", + ( + f("id", "id", "String", "the budget's identifier"), + f("account", "account", "String", "the account it applies to"), + f("domain", "domain", "String", "the domain that account is in"), + f("monthly", "monthly", "Double", "the monthly limit"), + f("currency", "currency", "String", "the currency of the limit"), + f("spent", "spent", "Double", "spend so far this month"), + f( + "onExceed", + "on_exceed", + "String", + "what happens at 100%: alert or block", + "onexceed", + ), + # Both are what a budget is read for, and both were dropped: + # the budgets tab rendered an empty percentage and never + # marked a blocked account. + f("percentUsed", "percent_used", "Double", "how much of it is used", "percentused"), + f("blocked", "blocked", "Boolean", "whether spend is being refused"), + ), + ), + Response( + "AiGpuCapacityResponse", + "aigpucapacity", + "GPU capacity for one class in one zone (SPEC.md section 4).", + ( + f("zone", "zone", "String", "the zone"), + f("gpuClass", "gpu_class", "String", "the GPU class", "gpuclass"), + f("gpusTotal", "gpus_total", "Integer", "GPUs discovered", "gpustotal"), + f("gpusFree", "gpus_free", "Integer", "GPUs not allocated", "gpusfree"), + f("nodesTotal", "nodes_total", "Integer", "hosts carrying the class tag", "nodestotal"), + f("nodesHealthy", "nodes_healthy", "Integer", "hosts up and enabled", "nodeshealthy"), + f( + "nodesFree", + "nodes_free", + "Integer", + "nodes in this class with no replica on them", + "nodesfree", + ), + ), + ), + Response( + "AiReconcilerRunResponse", + "aireconcilerrun", + "One reconciler run (SPEC.md section 4).", + ( + f("id", "id", "String", "the run's identifier"), + f("zone", "zone", "String", "the zone reconciled"), + f("status", "status", "String", "running, succeeded or failed"), + f("dryRun", "dry_run", "Boolean", "whether the run wrote anything", "dryrun"), + f("startedAt", "started_at", "String", "when the run began", "startedat"), + f("finishedAt", "finished_at", "String", "when the run ended", "finishedat"), + # The engine has always sent these; nothing declared them, so + # CloudStack dropped the list and the activity screen's + # actions tab had no data source at all. + f( + "actions", + "actions", + "String", + "what the run did, in order", + nested="AiReconcilerActionResponse", + ), + ), + ), + Response( + "AiSetupCheckResponse", + "aisetupcheck", + "One preflight check from the setup wizard (SPEC.md section 7).", + ( + f("name", "name", "String", "what was checked"), + f("status", "status", "String", "pass, warn, fail or skipped"), + f("detail", "detail", "String", "what was found"), + f("remedy", "remedy", "String", "what to do about it, where the check did not pass"), + ), + ), + Response( + "AiGpuClassProposalResponse", + "aigpuclassproposal", + "A GPU class the wizard proposes from CloudStack's host tags.", + ( + f("hostTag", "host_tag", "String", "the host tag seen", "hosttag"), + f("hosts", "hosts", "Integer", "healthy hosts carrying it"), + f("suggestedName", "suggested_name", "String", "a name for the class", "suggestedname"), + ), + ), + Response( + "AiPlaygroundSessionResponse", + "aiplaygroundsession", + "An ephemeral playground session (SPEC.md section 7).\n *\n * The key is" + " model-scoped and expires in fifteen minutes, so a real\n * key never reaches" + " the browser.", + ( + f("id", "id", "String", "the session key's identifier"), + # `apikey`, not `session_key`: the engine names a minted key + # the same way everywhere, and reading the wrong name here + # dropped the key at the one moment it exists — the same + # defect `createAiApiKey` had. The CloudStack-facing name + # stays `sessionkey`, which is what it is to a caller. + f( + "sessionKey", + "apikey", + "String", + "the short-lived, model-scoped key", + "sessionkey", + ), + f("model", "model", "String", "the model this session may use"), + f("baseUrl", "base_url", "String", "the endpoint to call", "baseurl"), + f("expires", "expires", "String", "when the session key expires"), + ), + ), +) + + +JAVA_READERS = { + "String": "getAsString", + "Integer": "getAsInt", + "Long": "getAsLong", + "Boolean": "getAsBoolean", + "Double": "getAsDouble", +} + + +def java_type(fl: Field) -> str: + """The declared type: a list for a nested field, else the scalar.""" + return f"List<{fl.nested}>" if fl.nested else fl.type + + +def render_response(response: Response) -> str: + fields = "\n\n".join( + f' @SerializedName("{fl.api}")\n' + + ( + f' @Param(description = "{fl.doc}", responseObject = {fl.nested}.class)\n' + if fl.nested + else f' @Param(description = "{fl.doc}")\n' + ) + + f" private {java_type(fl)} {fl.java};" + for fl in response.fields + ) + reads = "\n".join( + ( + f' mapped.{fl.java} = read{fl.nested}Map(body, "{fl.wire}");' + if fl.nested and fl.nested_map + else f' mapped.{fl.java} = read{fl.nested}List(body, "{fl.wire}");' + if fl.nested + else f' mapped.{fl.java} = read{fl.type}(body, "{fl.wire}");' + ) + for fl in response.fields + ) + getters = "\n\n".join( + f" public {java_type(fl)} get{fl.java[0].upper()}{fl.java[1:]}() {{\n" + f" return {fl.java};\n }}" + for fl in response.fields + ) + nested_readers = "\n\n".join( + f" private static List<{nested}> read{nested}List(" + "JsonObject body, String field) {\n" + f" List<{nested}> mapped = new ArrayList<>();\n" + " if (!body.has(field) || !body.get(field).isJsonArray()) {\n" + " return mapped;\n" + " }\n" + " for (JsonElement item : body.getAsJsonArray(field)) {\n" + " if (item.isJsonObject()) {\n" + f" mapped.add({nested}.from(item.getAsJsonObject()));\n" + " }\n" + " }\n" + " return mapped;\n }" + for nested in sorted( + {fl.nested for fl in response.fields if fl.nested and not fl.nested_map} + ) + ) + # The map form. Each entry's key is the object's name, so the key is + # merged into a copy of the value and the ordinary `from` does the + # rest — the nested class's fields are private, and only its own + # static factory can set them. + nested_map_readers = "\n\n".join( + f" private static List<{nested}> read{nested}Map(" + "JsonObject body, String field) {\n" + f" List<{nested}> mapped = new ArrayList<>();\n" + " if (!body.has(field) || !body.get(field).isJsonObject()) {\n" + " return mapped;\n" + " }\n" + " for (Map.Entry entry : " + "body.getAsJsonObject(field).entrySet()) {\n" + " if (!entry.getValue().isJsonObject()) {\n" + " continue;\n" + " }\n" + " JsonObject named = entry.getValue().getAsJsonObject().deepCopy();\n" + ' named.addProperty("name", entry.getKey());\n' + f" mapped.add({nested}.from(named));\n" + " }\n" + " return mapped;\n }" + for nested in sorted( + {fl.nested for fl in response.fields if fl.nested and fl.nested_map} + ) + ) + if nested_map_readers: + nested_readers = ( + f"{nested_readers}\n\n{nested_map_readers}" + if nested_readers + else nested_map_readers + ) + + def reader_for(t: str, reader: str) -> str: + if t != "String": + return ( + f" private static {t} read{t}(JsonObject body, String field) {{\n" + f" return body.has(field) && !body.get(field).isJsonNull()\n" + f" ? body.get(field).{reader}()\n" + f" : null;\n }}" + ) + # The engine sends some string-ish fields as arrays — a key's + # allowed models and CIDRs — and CloudStack carries them as + # one comma-separated value. `getAsString()` on an array + # throws "Array must have size 1, but has size 0", which is + # how a listed key came back as an error rather than a row. + return ( + " private static String readString(JsonObject body, String field) {\n" + " if (!body.has(field) || body.get(field).isJsonNull()) {\n" + " return null;\n" + " }\n" + " JsonElement value = body.get(field);\n" + " if (!value.isJsonArray()) {\n" + " return value.getAsString();\n" + " }\n" + " StringBuilder joined = new StringBuilder();\n" + " for (JsonElement part : value.getAsJsonArray()) {\n" + " if (joined.length() > 0) {\n" + ' joined.append(",");\n' + " }\n" + " joined.append(part.getAsString());\n" + " }\n" + " return joined.toString();\n" + " }" + ) + + readers = "\n\n".join( + reader_for(t, reader) + for t, reader in JAVA_READERS.items() + if any(fl.type == t and not fl.nested for fl in response.fields) + ) + if nested_readers: + readers = f"{readers}\n\n{nested_readers}" if readers else nested_readers + + # java.util only where a nested list needs it, so every other + # response keeps the import block it had. + collections = ( + ( + "import java.util.ArrayList;\nimport java.util.List;\n" + + ("import java.util.Map;\n" if nested_map_readers else "") + + "\n" + ) + if nested_readers + else "" + ) + + return f"""{LICENCE}{GENERATED}package org.apache.cloudstack.ai.api.response; + +{collections}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; + +/** {response.doc} */ +public class {response.name} extends BaseResponse {{ + +{fields} + + /** Map one engine object onto this response. */ + public static {response.name} from(JsonObject body) {{ + {response.name} mapped = new {response.name}(); + mapped.setObjectName("{response.object_name}"); + if (body == null) {{ + return mapped; + }} +{reads} + return mapped; + }} + +{getters} + +{readers} +}} +""" + + +# -------------------------------------------------------------------------- +# Commands +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Param: + name: str # API parameter name + java: str # Java field + type: str # STRING | INTEGER | LONG | BOOLEAN | UUID + doc: str + required: bool = False + #: Fully-qualified response class for `entityType`. Giving one makes + #: CloudStack check the caller may see the entity before the command + #: runs, and hand back its **internal numeric id** rather than the + #: UUID that was sent. + entity: str | None = None + #: Fully-qualified entity interface to translate that id back + #: through, for a body the engine can match against CloudStack's own + #: UUIDs. Without it an `entity` param would send a bare number. + resolve: str | None = None + #: The engine's JSON field name, where it differs from the Java + #: one. Leave it unset and the body carries the snake_case of the + #: Java name, which is what the engine's models use. + #: + #: It used to mean "this parameter belongs in the body at all", + #: and was therefore set only where the two names differed — + #: `baseModel` to `base_model`, `customDomain` to `custom_domain`. + #: Every parameter whose name already matched was left without + #: one and silently never sent, so seven v2 write commands posted + #: a body missing exactly the fields that needed no translation. + #: Whether a parameter is in the body is decided by the path and + #: the query list, not here. + wire: str | None = None + #: `@Parameter`'s own `length()`, which defaults to 255 — a cap no + #: PEM, JSONL or other blob can meet. CloudStack's + #: `UploadCustomCertificateCmd` sets 65535 for the same reason. + length: int | None = None + #: True where the engine's model declares `list[str]`. CloudStack + #: takes the value as a comma-separated string either way; without + #: this the body carried a string into a field typed as a list and + #: the engine answered 422. + is_list: bool = False + + +@dataclass(frozen=True) +class Command: + name: str + doc: str + path: str # may contain {java-field} placeholders + method: str = "GET" + is_async: bool = False + response: str = "" + items_key: str | None = None # set for list commands + #: CloudStack opens a detail view by calling the same list command with + #: `id=`. Without a declared `id` the parameter is dropped + #: in silence, the engine answers with everything, and AutogenView renders + #: the first row — so every detail page showed the first record in its + #: list. Set on any list command a screen has a detail view for. + filter_by_id: bool = False + #: The engine field that `id` is matched against. A row's key is + #: `record.id || record.name` (ListView.vue), so this is "id" wherever the + #: response carries one, and the field the screen builds its name from + #: otherwise. + identity: str = "id" + event: str | None = None + event_doing: str = "" + params: tuple[Param, ...] = () + query: tuple[str, ...] = () # java fields appended as query parameters + success_response: bool = False + #: "v1" ships in GA; "v2" is generated but registered only when + #: ai.services.v2.enabled is on, so the release boundary in + #: aisvc/api/commands.py holds on this side too. + release: str = "v1" + + +def p( + name, + java, + type_, + doc, + required=False, + entity=None, + wire=None, + resolve=None, + length=None, + is_list=False, +) -> Param: + return Param(name, java, type_, doc, required, entity, resolve, wire, length, is_list) + + +COMMANDS: tuple[Command, ...] = ( + # -- sourcing --------------------------------------------------------- + Command( + "searchAiHfModels", + "Searches the Hugging Face Hub for models.", + "/v1/hf/search", + response="AiHfModelResponse", + items_key="models", + params=( + p("query", "query", "STRING", "text to search for", required=True), + p("limit", "limit", "INTEGER", "how many results to return"), + ), + query=("query", "limit"), + ), + Command( + "checkAiHfModel", + "Reports whether a Hugging Face model can be served.", + "/v1/hf/check", + response="AiHfCheckResponse", + params=( + p( + "repoid", + "repoId", + "STRING", + "the repository to check", + required=True, + wire="repo_id", + ), + p("revision", "revision", "STRING", "the commit to check", required=True), + ), + query=("repoId", "revision"), + ), + Command( + "mirrorAiModel", + "Mirrors a pinned model revision into the registry.", + "/v1/models/mirror", + method="POST", + is_async=True, + response="AiModelResponse", + event="MODEL_MIRROR", + event_doing="mirroring model", + params=( + p( + "repoid", + "repoId", + "STRING", + "the repository to mirror", + required=True, + wire="repo_id", + ), + p("revision", "revision", "STRING", "the commit to pin", required=True), + ), + query=("repoId", "revision"), + ), + Command( + "approveAiModel", + "Approves a mirror request.", + "/v1/models/{modelId}/approve", + method="POST", + response="AiModelResponse", + event="MODEL_PUBLISH", + event_doing="approving model", + params=(p("id", "modelId", "STRING", "the model to approve", required=True),), + ), + Command( + "publishAiModel", + "Publishes a mirrored model to the catalog.", + "/v1/models/{modelId}/publish", + method="POST", + response="AiModelResponse", + event="MODEL_PUBLISH", + event_doing="publishing model", + params=( + p("id", "modelId", "STRING", "the model to publish", required=True), + p( + "visibility", + "visibility", + "STRING", + "domains or accounts to publish to", + wire="visibility", + ), + p("pricetier", "priceTier", "STRING", "the price tier", wire="price_tier"), + ), + ), + Command( + "listAiModels", + "Lists AI models published to the caller.", + "/v1/models", + response="AiModelResponse", + items_key="models", + filter_by_id=True, + identity="name", + ), + # -- deployments ------------------------------------------------------ + Command( + "listAiModelDeployments", + "Lists AI model deployments.", + "/v1/deployments", + response="AiDeploymentResponse", + items_key="deployments", + filter_by_id=True, + ), + Command( + "updateAiModelDeployment", + "Updates an AI model deployment.", + "/v1/deployments/{deploymentId}", + method="PATCH", + is_async=True, + response="AiDeploymentResponse", + event="MODEL_UPDATE", + event_doing="updating AI deployment", + params=( + p("id", "deploymentId", "STRING", "the deployment to update", required=True), + p("replicas", "replicas", "INTEGER", "replicas to run", wire="replicas"), + p( + "servingprofile", + "servingProfile", + "STRING", + "the serving profile to apply", + wire="serving_profile", + ), + ), + ), + Command( + "promoteAiRollout", + "Promotes the canary of a blue/green rollout.", + "/v1/deployments/{deploymentId}/rollout/promote", + method="POST", + is_async=True, + response="AiDeploymentResponse", + event="ROLLOUT_PROMOTE", + event_doing="promoting rollout of", + params=(p("id", "deploymentId", "STRING", "the deployment", required=True),), + ), + Command( + "rollbackAiRollout", + "Rolls a blue/green rollout back.", + "/v1/deployments/{deploymentId}/rollout/rollback", + method="POST", + is_async=True, + response="AiDeploymentResponse", + event="ROLLOUT_ROLLBACK", + event_doing="rolling back rollout of", + params=(p("id", "deploymentId", "STRING", "the deployment", required=True),), + ), + Command( + "listAiEndpoints", + "Lists the endpoints the caller may use.", + "/v1/endpoints", + response="AiEndpointResponse", + items_key="endpoints", + filter_by_id=True, + identity="model", + ), + # -- keys ------------------------------------------------------------- + Command( + "createAiApiKey", + "Creates a scoped API key. The secret is shown once.", + "/v1/keys", + method="POST", + response="AiApiKeyResponse", + event="KEY_CREATE", + event_doing="creating API key", + params=( + p("name", "name", "STRING", "a name for the key", required=True, wire="name"), + p( + "models", + "models", + "STRING", + "models this key may use; all if unset", + wire="allowed_models", + is_list=True, + ), + p( + "cidrlist", + "cidrList", + "STRING", + "CIDRs the key may be used from", + wire="cidrs", + is_list=True, + ), + p("expires", "expires", "STRING", "when the key should expire", wire="expires_at"), + p( + "ratelimitrpm", + "rateLimitRpm", + "INTEGER", + "requests per minute this key may make", + wire="rate_limit_rpm", + ), + ), + ), + Command( + "listAiApiKeys", + "Lists the caller's scoped API keys.", + "/v1/keys", + response="AiApiKeyResponse", + items_key="keys", + ), + Command( + "revokeAiApiKey", + "Revokes an API key.", + "/v1/keys/{keyId}", + method="DELETE", + success_response=True, + event="KEY_REVOKE", + event_doing="revoking API key", + params=(p("id", "keyId", "STRING", "the key to revoke", required=True),), + ), + # -- profiles --------------------------------------------------------- + Command( + "listAiServingProfiles", + "Lists serving profiles.", + "/v1/profiles/serving", + response="AiProfileResponse", + items_key="profiles", + filter_by_id=True, + ), + Command( + "createAiServingProfile", + "Creates a serving profile.", + "/v1/profiles/serving", + method="POST", + is_async=True, + response="AiProfileResponse", + event="PROFILE_UPDATE", + event_doing="creating serving profile", + params=( + p("name", "name", "STRING", "the profile name", required=True, wire="name"), + p( + "params", + "params", + "STRING", + "engine parameters as JSON", + required=True, + wire="params", + ), + ), + ), + Command( + "updateAiServingProfile", + "Updates a serving profile, rolling it out.", + "/v1/profiles/serving/{profileId}", + method="PATCH", + is_async=True, + response="AiProfileResponse", + event="PROFILE_UPDATE", + event_doing="updating serving profile", + params=( + p("id", "profileId", "STRING", "the profile to update", required=True), + p("params", "params", "STRING", "engine parameters as JSON", wire="params"), + ), + ), + Command( + "deleteAiServingProfile", + "Deletes a serving profile.", + "/v1/profiles/serving/{profileId}", + method="DELETE", + is_async=True, + response="AiProfileResponse", + event="PROFILE_UPDATE", + event_doing="deleting serving profile", + params=(p("id", "profileId", "STRING", "the profile to delete", required=True),), + ), + Command( + "listAiGenerationProfiles", + "Lists generation profiles.", + "/v1/profiles/generation", + response="AiProfileResponse", + items_key="profiles", + filter_by_id=True, + ), + Command( + "createAiGenerationProfile", + "Creates a generation profile.", + "/v1/profiles/generation", + method="POST", + response="AiProfileResponse", + event="PROFILE_UPDATE", + event_doing="creating generation profile", + params=( + p("name", "name", "STRING", "the profile name", required=True, wire="name"), + p( + "params", + "params", + "STRING", + "parameters and policies as JSON", + required=True, + wire="params", + ), + ), + ), + Command( + "updateAiGenerationProfile", + "Updates a generation profile.", + "/v1/profiles/generation/{profileId}", + method="PATCH", + event="PROFILE_UPDATE", + event_doing="updating generation profile", + response="AiProfileResponse", + params=( + p("id", "profileId", "STRING", "the profile to update", required=True), + p("params", "params", "STRING", "parameters and policies as JSON", wire="params"), + ), + ), + Command( + "deleteAiGenerationProfile", + "Deletes a generation profile.", + "/v1/profiles/generation/{profileId}", + method="DELETE", + success_response=True, + event="PROFILE_UPDATE", + event_doing="deleting generation profile", + params=(p("id", "profileId", "STRING", "the profile to delete", required=True),), + ), + Command( + "assignAiTuningProfile", + "Assigns a tuning profile at a scope.", + "/v1/profiles/assignments", + method="POST", + is_async=True, + response="AiProfileResponse", + event="PROFILE_UPDATE", + event_doing="assigning tuning profile", + params=( + p( + "scope", + "scope", + "STRING", + "domain, account, deployment or key", + required=True, + wire="scope", + ), + p("target", "target", "STRING", "what to assign it to", required=True, wire="target"), + p( + "profile", + "profile", + "STRING", + "the profile to assign", + required=True, + wire="profile", + ), + ), + ), + Command( + "getAiEffectiveParameters", + "Reports every resolved parameter and the level that set it.", + "/v1/profiles/effective", + response="AiEffectiveParameterResponse", + items_key="parameters", + params=(p("model", "model", "STRING", "the deployment to resolve for", required=True),), + query=("model",), + ), + # -- usage and budgets ------------------------------------------------ + Command( + "listAiUsage", + "Lists metered usage.", + "/v1/usage", + response="AiUsageResponse", + items_key="usage", + params=( + p("startdate", "startDate", "STRING", "start of the period", wire="start_date"), + p("enddate", "endDate", "STRING", "end of the period", wire="end_date"), + ), + query=("startDate", "endDate"), + filter_by_id=True, + identity="model", + ), + Command( + "listAiBudgets", + "Lists budgets.", + "/v1/budgets", + response="AiBudgetResponse", + items_key="budgets", + ), + Command( + "createAiBudget", + "Creates a monthly budget.", + "/v1/budgets", + method="POST", + response="AiBudgetResponse", + event="BUDGET_UPDATE", + event_doing="creating budget for", + params=( + p( + "account", + "account", + "STRING", + "the account the budget applies to", + required=True, + wire="account", + ), + # Required with the account: a CloudStack account name is + # unique only within its domain, so the two together are + # what names a budget. + p( + "domain", + "domainPath", + "STRING", + "the domain path that account is in", + required=True, + wire="domain", + ), + p("monthly", "monthly", "STRING", "the monthly limit", required=True, wire="monthly"), + p("currency", "currency", "STRING", "the currency", wire="currency"), + p("onexceed", "onExceed", "STRING", "alert or block at 100%", wire="on_exceed"), + ), + ), + Command( + "updateAiBudget", + "Updates a budget.", + "/v1/budgets/{budgetId}", + method="PATCH", + response="AiBudgetResponse", + event="BUDGET_UPDATE", + event_doing="updating budget for", + params=( + p("id", "budgetId", "STRING", "the budget to update", required=True), + p("monthly", "monthly", "STRING", "the monthly limit", wire="monthly"), + # The engine's BudgetPatch takes one and the command never + # offered it, so a budget's currency could be set at creation + # and never corrected. + p("currency", "currency", "STRING", "the currency of the limit", wire="currency"), + p("onexceed", "onExceed", "STRING", "alert or block at 100%", wire="on_exceed"), + ), + ), + Command( + "deleteAiBudget", + "Deletes a budget.", + "/v1/budgets/{budgetId}", + method="DELETE", + success_response=True, + event="BUDGET_UPDATE", + event_doing="deleting budget for", + params=(p("id", "budgetId", "STRING", "the budget to delete", required=True),), + ), + # -- tenant experience ------------------------------------------------ + Command( + "createAiPlaygroundSession", + "Mints a short-lived, model-scoped key for the playground.", + "/v1/playground/sessions", + method="POST", + event="PLAYGROUND_SESSION", + event_doing="opening a playground session for", + response="AiPlaygroundSessionResponse", + params=( + p( + "model", + "model", + "STRING", + "the model to open a session against", + required=True, + wire="model", + ), + ), + ), + # -- operations ------------------------------------------------------- + Command( + "listAiSetupChecks", + "Runs the setup wizard's preflight checks.", + "/v1/setup/preflight", + response="AiSetupCheckResponse", + items_key="checks", + ), + Command( + "discoverAiGpuClasses", + "Proposes GPU classes from the tags on healthy hosts.", + "/v1/setup/gpu-discovery", + response="AiGpuClassProposalResponse", + items_key="classes", + ), + Command( + "runAiSetupSelfTest", + "Runs the setup self-test for a zone.", + "/v1/setup/selftest", + method="POST", + is_async=True, + response="AiReconcilerRunResponse", + event="MODEL_DEPLOY", + event_doing="running the AI Services self-test for", + params=(p("zoneid", "zoneId", "STRING", "the zone to test", required=True, wire="zone"),), + ), + Command( + "listAiGpuCapacity", + "Lists GPU capacity per zone and class.", + "/v1/capacity", + response="AiGpuCapacityResponse", + items_key="classes", + ), + Command( + "drainAiNode", + "Drains a GPU node before maintenance.", + "/v1/nodes/{nodeId}/drain", + method="POST", + is_async=True, + response="AiReconcilerRunResponse", + event="NODE_DRAIN", + event_doing="draining GPU node", + params=( + p("id", "nodeId", "STRING", "the node to drain", required=True), + # A query parameter on the engine, and the reason an operator + # drains at all when a zone is tight: without it a drain is + # refused where the replicas have nowhere else to go. + p("force", "force", "BOOLEAN", "drain even with no room for the replicas elsewhere"), + ), + query=("force",), + ), + Command( + "listAiReconcilerRuns", + "Lists reconciler runs.", + "/v1/runs", + response="AiReconcilerRunResponse", + items_key="runs", + filter_by_id=True, + ), + # -- tier 2 (SPEC.md section 8) --------------------------------------- + # Generated, but registered only when ai.services.v2.enabled is on: + # the release boundary in aisvc/api/commands.py holds here too. + Command( + "listAiAdapters", + "Lists the LoRA adapters this account may use.", + "/v1/adapters", + response="AiAdapterResponse", + items_key="adapters", + release="v2", + filter_by_id=True, + ), + Command( + "uploadAiAdapter", + "Registers a LoRA adapter.", + "/v1/adapters", + method="POST", + is_async=True, + response="AiAdapterResponse", + event="ADAPTER_UPLOAD", + event_doing="registering adapter", + release="v2", + params=( + p("name", "name", "STRING", "a name for the adapter", required=True), + p( + "basemodel", + "baseModel", + "STRING", + "the base it serves on", + required=True, + wire="base_model", + ), + p("rank", "rank", "INTEGER", "its LoRA rank", required=True), + # Required because the engine checks it against + # MAX_ADAPTER_BYTES. Defaulting it would turn that limit + # off; the caller declares it until artefacts are fetched + # and it can be measured instead. + p( + "sizebytes", + "sizeBytes", + "INTEGER", + "size of the adapter in bytes", + required=True, + wire="size_bytes", + ), + # Required in practice, though the engine's field defaults + # to empty: `validate_adapter` refuses an adapter whose + # files contain no `.safetensors`, so a command that could + # not send them could never register one. It had no + # `files` parameter at all, so every upload through + # CloudStack was refused with "no adapter weights found". + p( + "files", + "files", + "STRING", + "the adapter's artefact filenames; one must be a .safetensors", + required=True, + is_list=True, + wire="files", + ), + p("uri", "uri", "STRING", "where its artefacts are"), + ), + ), + Command( + "deleteAiAdapter", + "Deletes a LoRA adapter.", + "/v1/adapters/{adapterId}", + method="DELETE", + success_response=True, + event="ADAPTER_DELETE", + event_doing="deleting adapter", + release="v2", + params=(p("id", "adapterId", "STRING", "the adapter to delete", required=True),), + ), + Command( + "createAiBatch", + "Submits a batch inference job.", + "/v1/batches", + method="POST", + is_async=True, + response="AiBatchResponse", + event="BATCH_CREATE", + event_doing="submitting batch", + release="v2", + params=( + p("model", "model", "STRING", "the model to run against", required=True), + # The JSONL itself. The command carried only `inputuri`, and + # the engine parses `input` unconditionally — so every batch + # submitted through CloudStack was refused with "the batch + # input file has no requests", whatever the caller sent. + # `length` because 255 is the `@Parameter` default and no + # batch file meets it. + p( + "input", + "input", + "STRING", + "the batch's JSONL, one request per line", + required=True, + wire="input", + length=65535, + ), + p("inputuri", "inputUri", "STRING", "where the JSONL input is", wire="input_uri"), + ), + ), + Command( + "listAiBatches", + "Lists batch jobs.", + "/v1/batches", + response="AiBatchResponse", + items_key="batches", + release="v2", + filter_by_id=True, + ), + Command( + "cancelAiBatch", + "Cancels a batch job.", + "/v1/batches/{batchId}/cancel", + method="POST", + # Sync: SPEC section 8 marks only batch *creation* async, and + # the engine answers 200 here. Declared async it could never + # succeed, because an async command treats 200 as a refusal. + response="AiBatchResponse", + event="BATCH_CANCEL", + event_doing="cancelling batch", + release="v2", + params=(p("id", "batchId", "STRING", "the batch to cancel", required=True),), + ), + Command( + "getAiBatchResults", + "Downloads a batch job's results.", + "/v1/batches/{batchId}/results", + response="AiBatchResponse", + release="v2", + params=(p("id", "batchId", "STRING", "the batch to read", required=True),), + ), + Command( + "listAiGuardrailProfiles", + "Lists guardrail profiles.", + "/v1/profiles/guardrail", + response="AiGuardrailProfileResponse", + items_key="profiles", + release="v2", + filter_by_id=True, + ), + Command( + "createAiGuardrailProfile", + "Creates a guardrail profile.", + "/v1/profiles/guardrail", + method="POST", + response="AiGuardrailProfileResponse", + event="PROFILE_UPDATE", + event_doing="creating guardrail profile", + release="v2", + params=( + p("name", "name", "STRING", "a name for the profile", required=True), + p("scope", "scope", "STRING", "the level to bind it at"), + p("target", "target", "STRING", "the domain, account or deployment"), + p("preset", "preset", "STRING", "a shipped profile to start from"), + ), + ), + Command( + "updateAiGuardrailProfile", + "Updates a guardrail profile.", + "/v1/profiles/guardrail/{profileId}", + method="PATCH", + response="AiGuardrailProfileResponse", + event="PROFILE_UPDATE", + event_doing="updating guardrail profile", + release="v2", + params=( + p("id", "profileId", "STRING", "the profile to update", required=True), + p("target", "target", "STRING", "the scope to bind it to"), + ), + ), + Command( + "deleteAiGuardrailProfile", + "Deletes a guardrail profile.", + "/v1/profiles/guardrail/{profileId}", + method="DELETE", + success_response=True, + event="PROFILE_UPDATE", + event_doing="deleting guardrail profile", + release="v2", + params=(p("id", "profileId", "STRING", "the profile to delete", required=True),), + ), + Command( + "runAiModelEvaluation", + "Records a pre-publish evaluation.", + "/v1/models/{modelName}/evaluations", + method="POST", + is_async=True, + response="AiEvaluationResponse", + event="MODEL_UPDATE", + event_doing="evaluating model", + release="v2", + params=( + p("model", "modelName", "STRING", "the model evaluated", required=True), + p("revision", "revision", "STRING", "the revision evaluated", required=True), + ), + ), + Command( + "listAiEvaluations", + "Lists a model's evaluations.", + "/v1/models/{modelName}/evaluations", + response="AiEvaluationResponse", + items_key="evaluations", + release="v2", + params=(p("model", "modelName", "STRING", "the model to list", required=True),), + ), + Command( + "uploadAiCertificate", + "Uploads a TLS certificate for a custom domain.", + "/v1/certificates", + method="POST", + response="AiCertificateResponse", + event="CERTIFICATE_UPLOAD", + event_doing="uploading certificate for", + release="v2", + params=( + p( + "customdomain", + "customDomain", + "STRING", + "the domain it covers", + required=True, + wire="custom_domain", + ), + p( + "certificate", + "certificate", + "STRING", + "the PEM certificate", + required=True, + length=65535, + ), + p( + "privatekey", + "privateKey", + "STRING", + "the PEM private key", + required=True, + wire="private_key", + length=65535, + ), + ), + ), + Command( + "listAiCertificates", + "Lists uploaded certificates.", + "/v1/certificates", + response="AiCertificateResponse", + items_key="certificates", + release="v2", + filter_by_id=True, + ), + Command( + "replaceAiCertificate", + "Replaces a certificate, keeping its id.", + "/v1/certificates/{certificateId}", + method="PATCH", + event="CERTIFICATE_REPLACE", + event_doing="replacing certificate for", + response="AiCertificateResponse", + release="v2", + params=( + p("id", "certificateId", "STRING", "the certificate to replace", required=True), + p( + "certificate", + "certificate", + "STRING", + "the PEM certificate", + required=True, + length=65535, + ), + p( + "privatekey", + "privateKey", + "STRING", + "the PEM private key", + required=True, + wire="private_key", + length=65535, + ), + ), + ), + Command( + "deleteAiCertificate", + "Deletes a certificate.", + "/v1/certificates/{certificateId}", + method="DELETE", + success_response=True, + event="CERTIFICATE_DELETE", + event_doing="deleting certificate for", + release="v2", + params=(p("id", "certificateId", "STRING", "the certificate to delete", required=True),), + ), + Command( + "listAiPrivateEndpoints", + "Lists private endpoints and how each one is reachable.", + "/v1/endpoints/private", + response="AiPrivateEndpointResponse", + items_key="endpoints", + release="v2", + filter_by_id=True, + ), + Command( + "createAiPrivateEndpoint", + "Attaches an endpoint to a tenant network.", + "/v1/endpoints/private", + method="POST", + is_async=True, + response="AiPrivateEndpointResponse", + event="MODEL_UPDATE", + event_doing="attaching private endpoint", + release="v2", + params=( + p("deployment", "deployment", "STRING", "the deployment to front", required=True), + p( + "networkid", + "networkId", + "UUID", + "the VPC tier to attach to", + entity="org.apache.cloudstack.api.response.NetworkResponse", + resolve="com.cloud.network.Network", + wire="network_id", + ), + p( + "publicenabled", + "publicEnabled", + "BOOLEAN", + "whether the public endpoint stays on", + wire="public_enabled", + ), + p("customdomain", "customDomain", "STRING", "a custom domain", wire="custom_domain"), + # Without this every private endpoint was created with the + # engine's default, `tls: none` — so `certificateid` below + # could never mean anything, and a TLS-terminated private + # endpoint could not be made through CloudStack at all. + p( + "tls", + "tls", + "STRING", + "where its certificate comes from: none, acme or uploaded", + ), + p( + "certificateid", + "certificateId", + "STRING", + "an uploaded certificate for it", + wire="certificate_id", + ), + ), + ), + Command( + "deleteAiPrivateEndpoint", + "Removes a private endpoint.", + "/v1/endpoints/private/{exposureId}", + method="DELETE", + is_async=True, + response="AiPrivateEndpointResponse", + event="MODEL_UPDATE", + event_doing="removing private endpoint", + release="v2", + params=(p("id", "exposureId", "STRING", "the exposure to remove", required=True),), + ), +) + + +def class_name(command: str) -> str: + return command[0].upper() + command[1:] + "Cmd" + + +def _simple(fqcn: str) -> str: + """The class name a Java source file refers to, given an import.""" + return fqcn.rsplit(".", 1)[-1] + + +def render_params(params: tuple[Param, ...]) -> str: + out = [] + for param in params: + entity = ( + f",\n entityType = {_simple(param.entity)}.class" if param.entity else "" + ) + required = ", required = true" if param.required else "" + # @Parameter caps a STRING at 255 unless told otherwise, which + # no PEM or other blob can meet. + length = f", length = {param.length}" if param.length else "" + java_type = { + "STRING": "String", + "INTEGER": "Integer", + "LONG": "Long", + "BOOLEAN": "Boolean", + "UUID": "Long", + }[param.type] + out.append( + f' @Parameter(name = "{param.name}", type = CommandType.{param.type}{entity}' + f"{required}{length},\n" + f' description = "{param.doc}")\n' + f" private {java_type} {param.java};" + ) + return "\n\n".join(out) + + +def render_path(command: Command) -> str: + path = command.path + expr = '"' + path + '"' + for param in command.params: + placeholder = "{" + param.java + "}" + if placeholder in path: + expr = expr.replace(placeholder, '" + ' + param.java + ' + "') + expr = expr.replace(' + ""', "").replace('"" + ', "") + body = f" String path = {expr};" + for java in command.query: + body += f'\n path = withQuery(path, "{_wire_for(command, java)}", {java});' + body += "\n return path;" + return body + + +def _wire_for(command: Command, java: str) -> str: + for param in command.params: + if param.java == java: + return param.wire or param.name + return java + + +def _body_lines(param: Param) -> str: + """One parameter's contribution to the request body. + + A `resolve` parameter arrives as the internal id CloudStack + translated the UUID into, and the engine stores what it is sent and + compares it against the UUIDs CloudStack returns from its own list + calls. Sending the number would record an id matching nothing, so + it is translated back here. + """ + if param.is_list: + # CloudStack hands a list parameter over as a comma-separated + # string; the engine's model wants an array. + return ( + f" if ({param.java} != null) {{\n" + f" JsonArray values{param.java[0].upper()}{param.java[1:]} =" + f" new JsonArray();\n" + f' for (String part : {param.java}.split(",")) {{\n' + f" String trimmed = part.trim();\n" + f" if (!trimmed.isEmpty()) {{\n" + f" values{param.java[0].upper()}{param.java[1:]}" + f".add(trimmed);\n" + f" }}\n" + f" }}\n" + f' body.add("{wire_name(param)}",' + f" values{param.java[0].upper()}{param.java[1:]});\n" + f" }}" + ) + + if not param.resolve: + return ( + f" if ({param.java} != null) {{\n" + f' body.addProperty("{wire_name(param)}", {param.java});\n' + f" }}" + ) + + cls = _simple(param.resolve) + local = "resolved" + cls + return ( + f" if ({param.java} != null) {{\n" + f" {cls} {local} = _entityMgr.findById({cls}.class, {param.java});\n" + f" if ({local} == null) {{\n" + f" throw new InvalidParameterValueException(\n" + f' "Unable to find a {cls.lower()} with the given id");\n' + f" }}\n" + f' body.addProperty("{wire_name(param)}", {local}.getUuid());\n' + f" }}" + ) + + +def snake(name: str) -> str: + """The engine's spelling of a Java field name.""" + return re.sub(r"(? str: + """The JSON field this parameter travels as.""" + return param.wire or snake(param.java) + + +def render_body(command: Command) -> str: + body_params = [ + param + for param in command.params + if "{" + param.java + "}" not in command.path and param.java not in command.query + ] + if not body_params: + return "" + lines = "\n".join(_body_lines(param) for param in body_params) + return f""" + @Override + protected String engineBody() {{ + JsonObject body = new JsonObject(); +{lines} + return body.toString(); + }} +""" + + +#: Commands whose response carries a credential, so CloudStack knows not +#: to treat the body as ordinary. `createAiPlaygroundSession` belongs here +#: for the same reason `createAiApiKey` does — it mints a real key, even +#: though that key is model-scoped and expires in fifteen minutes. It was +#: absent while the mapping dropped the key, which made the declaration +#: accidentally true and is no reason to leave it. +SECRET_IN_RESPONSE = frozenset({"createAiApiKey", "createAiPlaygroundSession"}) + + +def event_methods(command: Command) -> str: + """The two overrides that let CloudStack record this command. + + A command with no event name records nothing, which is how reads + stay out of the operator's log: `AiServicesSyncCmd.getEventType` + returns null by default and every list command inherits it. + + Both base classes route their work through + `AiServicesService.recordEvent` when a type is present, because the + interceptor that writes Completed and Failed is a Spring AOP + advisor and only sees methods on beans — never a command's own + `execute()`, which CloudStack builds unproxied. + """ + if not command.event: + return "" + return ( + "\n\n @Override\n public String getEventType() {\n" + f" return AiServicesEvents.{command.event};\n }}\n\n" + " @Override\n public String getEventDescription() {\n" + f' return "{command.event_doing} " + {_subject(command)};\n }}' + ) + + +def render_command(command: Command) -> str: + cls = class_name(command.name) + imports = [ + "org.apache.cloudstack.acl.RoleType", + "org.apache.cloudstack.api.APICommand", + ] + # Only where there is a @Parameter to annotate. CloudStack's own build + # runs checkstyle with cloud-style.xml, where an unused import is an + # error — so emitting this unconditionally turned sixteen parameterless + # list commands into sixteen build failures in a CloudStack tree, while + # the standalone pom here, which runs no checkstyle, stayed green. + if command.params: + imports.append("org.apache.cloudstack.api.Parameter") + if command.success_response: + imports.append("org.apache.cloudstack.api.response.SuccessResponse") + response_type = "SuccessResponse" + else: + imports.append(f"org.apache.cloudstack.ai.api.response.{command.response}") + response_type = command.response + + has_body = bool(render_body(command)) + if has_body: + imports.append("com.google.gson.JsonObject") + if any(param.is_list for param in command.params): + imports.append("com.google.gson.JsonArray") + + # An entityType or a resolution names a class the file must import. + # Emitting the reference without the import is how setting `entity` + # used to produce Java that did not compile. + for param in command.params: + if param.entity: + imports.append(param.entity) + if param.resolve: + imports.append(param.resolve) + imports.append("com.cloud.exception.InvalidParameterValueException") + if command.event: + imports.append("org.apache.cloudstack.ai.AiServicesEvents") + if command.is_async: + imports.append("org.apache.cloudstack.ai.engine.EngineJob") + else: + # Both list and plain sync commands take a JsonObject: one per + # item, one for the whole body. + imports.append("com.google.gson.JsonObject") + + import_block = "\n".join( + f"import {i};" for i in sorted(set(imports)) if not i.startswith("com.google") + ) + gson_block = "\n".join( + f"import {i};" for i in sorted(set(imports)) if i.startswith("com.google") + ) + if gson_block: + import_block += "\n\n" + gson_block + + naming = f' public static final String APINAME = "{command.name}";' + params = render_params(command.params) + path_method = ( + " @Override\n protected String enginePath() {\n" + render_path(command) + "\n }" + ) + method_override = ( + f"\n @Override\n protected String engineMethod() {{\n" + f' return "{command.method}";\n }}\n' + if command.method != ("POST" if command.is_async else "GET") + else "" + ) + + if command.is_async: + extends = "AiServicesAsyncCmd" + success = ( + " @Override\n protected void onSuccess(EngineJob job) {\n" + f" {response_type} response = {response_type}.from(job.getResult());\n" + " response.setResponseName(getCommandName());\n" + " setResponseObject(response);\n }" + event_methods(command) + ) + elif command.items_key: + extends = f"AiServicesListCmd<{response_type}>" + success = ( + " @Override\n protected String itemsKey() {\n" + f' return "{command.items_key}";\n }}\n\n' + " @Override\n" + f" protected {response_type} mapItem(JsonObject item) {{\n" + f" return {response_type}.from(item);\n }}" + ) + if command.filter_by_id: + # The `id` field lives on the base class, which every list + # command shares; only the field to match it against varies. + success += ( + "\n\n @Override\n protected boolean filtersById() {\n" + " return true;\n }" + ) + if command.identity != "id": + success += ( + "\n\n @Override\n protected String identityField() {\n" + f' return "{command.identity}";\n }}' + ) + else: + extends = "AiServicesSyncCmd" + if command.success_response: + success = ( + " @Override\n protected void onSuccess(JsonObject body) {\n" + " SuccessResponse response = new SuccessResponse(getCommandName());\n" + " response.setSuccess(true);\n" + " setResponseObject(response);\n }" + ) + else: + success = ( + " @Override\n protected void onSuccess(JsonObject body) {\n" + f" {response_type} response = {response_type}.from(body);\n" + " response.setResponseName(getCommandName());\n" + " setResponseObject(response);\n }" + ) + # A sync write records its outcome too. Only the async half + # used to carry these, so every synchronous write — budgets, + # keys, certificates, guardrail profiles — completed in + # silence. + success += event_methods(command) + + sections = [naming] + if params: + sections.append(params) + sections.append(path_method + method_override) + body = render_body(command) + if body: + sections.append(body.strip()) + sections.append(success) + + return f"""{LICENCE}{GENERATED}package org.apache.cloudstack.ai.api.command; + +{import_block} + +/** {command.doc} (SPEC.md section 9). */ +@APICommand(name = {cls}.APINAME, + description = "{command.doc}", + responseObject = {response_type}.class, + requestHasSensitiveInfo = false, + responseHasSensitiveInfo = {str(command.name in SECRET_IN_RESPONSE).lower()}, + authorized = {{{authorized_roles(command.name)}}}) +public class {cls} extends {extends} {{ + +{chr(10).join(s + chr(10) for s in sections).rstrip()} +}} +""" + + +def authorized_roles(name: str) -> str: + """The RoleTypes that may call this command, for `@APICommand`. + + CloudStack's `DynamicRoleBasedAPIAccessChecker.start()` reads this + annotation off every `PluggableService`'s commands and consults it + whenever no explicit `role_permissions` rule matches the caller's + role. Without it a plugin's commands reach root admin alone, which + is how a live management server denied a tenant all thirty-eight. + + An explicit rule still wins either way: the checker returns on the + first matching rule, so the restricted default roles — which end + in `* DENY` — never reach this fallback, and an operator can deny + or grant any of these by hand. + + `ResourceAdmin` is deliberately never emitted. The engine models + three roles, and inventing a grant for a fourth is worse than + leaving it to an operator who wants one. + """ + command = next((c for c in ENGINE_COMMANDS if c.name == name), None) + if command is None: + raise SystemExit(f"{name} is not in aisvc/api/commands.py") + order = ["Admin", "DomainAdmin", "User"] + names = sorted({role.value for role in command.roles}, key=order.index) + return ", ".join(f"RoleType.{n}" for n in names) + + +def _subject(command: Command) -> str: + for param in command.params: + if param.required: + return param.java + return '"the platform"' + + +SAMPLE_VALUES = { + "String": "sample", + "Integer": 7, + "Long": 1234, + "Boolean": True, + "Double": 1.5, +} + + +def render_fixture() -> str: + """A fully-populated engine object per response type. + + Emitted as a test resource so the Java round-trip test exercises + every mapped field without that list being maintained twice. + """ + import json + + fixture = { + response.name: {fl.wire: SAMPLE_VALUES[fl.type] for fl in response.fields} + for response in RESPONSES + } + return json.dumps(fixture, indent=2, sort_keys=True) + "\n" + + +def main() -> int: + written = [] + for response in RESPONSES: + target = PKG / "response" / f"{response.name}.java" + target.write_text(render_response(response), encoding="utf-8") + written.append(target) + for command in COMMANDS: + target = PKG / "command" / f"{class_name(command.name)}.java" + target.write_text(render_command(command), encoding="utf-8") + written.append(target) + + fixture = ROOT / "src/test/resources/generated-engine-objects.json" + fixture.parent.mkdir(parents=True, exist_ok=True) + fixture.write_text(render_fixture(), encoding="utf-8") + written.append(fixture) + + print(f"generated {len(written)} files") + registration = "\n".join( + f" commands.add({class_name(c.name)}.class);" for c in COMMANDS if c.release == "v1" + ) + registration += "\n\n// v2, registered only when ai.services.v2.enabled:\n" + registration += "\n".join( + f" commands.add({class_name(c.name)}.class);" for c in COMMANDS if c.release == "v2" + ) + (ROOT / "target" / "generated-registration.txt").parent.mkdir(parents=True, exist_ok=True) + (ROOT / "target" / "generated-registration.txt").write_text(registration, encoding="utf-8") + print("registration snippet written to target/generated-registration.txt") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/plugins/pom.xml b/plugins/pom.xml index 92768827f658..47a2d7b32eb9 100755 --- a/plugins/pom.xml +++ b/plugins/pom.xml @@ -56,6 +56,7 @@ alert-handlers/snmp-alerts alert-handlers/syslog-alerts + api/ai-services api/discovery api/rate-limit api/solidfire-intg-test diff --git a/ui/public/locales/en.json b/ui/public/locales/en.json index a3d3a2285ac4..4f7c1b7af000 100644 --- a/ui/public/locales/en.json +++ b/ui/public/locales/en.json @@ -4569,5 +4569,155 @@ "GB*Month": "GB * Month", "IP*Month": "IP * Month", "Policy*Month": "Policy * Month", -"message.kms.key.optional": "Optional: Select a KMS key for encryption. If not selected, legacy passphrase encryption will be used." +"message.kms.key.optional": "Optional: Select a KMS key for encryption. If not selected, legacy passphrase encryption will be used.", +"label.ai.activity": "Activity", +"label.ai.adapters": "Adapters", +"label.ai.api.keys": "API keys", +"label.ai.approve.model": "Approve for the catalog", +"label.ai.assign.profile": "Assign profile", +"label.ai.basemodel": "Base model", +"label.ai.baseurl": "Base URL", +"label.ai.batch": "Batch", +"label.ai.batch.results": "Download results", +"label.ai.batches": "Batch jobs", +"label.ai.budgets": "Budgets", +"label.ai.cancel.batch": "Cancel batch", +"label.ai.candidate": "Candidate", +"label.ai.certificates": "Certificates", +"label.ai.check.compatibility": "Check compatibility", +"label.ai.checks": "Checks", +"label.ai.compatible": "Compatible", +"label.ai.contextlength": "Context length", +"label.ai.cost": "Cost", +"label.ai.create.batch": "Submit batch", +"label.ai.create.budget": "Set budget", +"label.ai.create.generation.profile": "Create generation profile", +"label.ai.create.guardrail.profile": "Create guardrail profile", +"label.ai.create.private.endpoint": "Attach private endpoint", +"label.ai.create.serving.profile": "Create serving profile", +"label.ai.customdomain": "Custom domain", +"label.ai.delete.adapter": "Delete adapter", +"label.ai.delete.certificate": "Delete certificate", +"label.ai.delete.deployment": "Delete endpoint", +"label.ai.delete.generation.profile": "Delete generation profile", +"label.ai.delete.guardrail.profile": "Delete guardrail profile", +"label.ai.delete.private.endpoint": "Remove private endpoint", +"label.ai.delete.serving.profile": "Delete serving profile", +"label.ai.deploy.model": "Deploy model", +"label.ai.deployment": "Deployment", +"label.ai.deployments": "Deployments", +"label.ai.detail": "Detail", +"label.ai.discover.gpu.classes": "Discover GPU classes", +"label.ai.downloads": "Downloads", +"label.ai.drain.node": "Drain node", +"label.ai.drift": "Drift", +"label.ai.effective.parameters": "Effective parameters", +"label.ai.endpoints": "Endpoints", +"label.ai.evaluations": "Evaluations", +"label.ai.expires": "Expires", +"label.ai.exposure": "Exposure", +"label.ai.finished": "Finished", +"label.ai.fleet.health": "Fleet health", +"label.ai.generation.profiles": "Generation settings", +"label.ai.gpu.capacity": "GPU capacity", +"label.ai.gpuclass": "GPU class", +"label.ai.gpuhours": "GPU hours", +"label.ai.gpumemoryutilization": "GPU memory utilization", +"label.ai.guardrails": "Guardrail profiles", +"label.ai.host": "Host", +"label.ai.hosttag": "Host tag", +"label.ai.huggingface": "Hugging Face", +"label.ai.inputtokens": "Input tokens", +"label.ai.inputuri": "Input URI", +"label.ai.license": "License", +"label.ai.livecolour": "Live colour", +"label.ai.maxmodellen": "Max model length", +"label.ai.maxnumseqs": "Max concurrent sequences", +"label.ai.mirror.model": "Mirror model", +"label.ai.model": "Model", +"label.ai.model.catalog": "Model catalog", +"label.ai.nodes": "Nodes", +"label.ai.outputtokens": "Output tokens", +"label.ai.outputuri": "Output URI", +"label.ai.parameter": "Parameter", +"label.ai.playground": "Playground", +"label.ai.pricetier": "Price tier", +"label.ai.private.endpoints": "Private endpoints", +"label.ai.problems": "Problems", +"label.ai.promote.rollout": "Promote", +"label.ai.publicenabled": "Public", +"label.ai.publish.model": "Publish to tenants", +"label.ai.published": "Published", +"label.ai.rank": "Rank", +"label.ai.recorded": "Recorded", +"label.ai.registry": "Model registry", +"label.ai.remedy": "Remedy", +"label.ai.replace.certificate": "Replace certificate", +"label.ai.replicas": "Replicas", +"label.ai.repo": "Repository", +"label.ai.requestcount": "Requests", +"label.ai.revision": "Revision", +"label.ai.rollback.rollout": "Roll back", +"label.ai.rollouts": "Rollouts", +"label.ai.run.actions": "Actions", +"label.ai.run.evaluation": "Run evaluation", +"label.ai.run.self.test": "Run self-test", +"label.ai.serial": "Serial number", +"label.ai.servedmodelname": "Served model name", +"label.ai.serving.profiles": "Serving profiles", +"label.ai.setup": "Setup", +"label.ai.sha256": "SHA-256", +"label.ai.sizebytes": "Size in bytes", +"label.ai.snippets": "Code snippets", +"label.ai.spechash": "Spec hash", +"label.ai.target": "Target", +"label.ai.task": "Task", +"label.ai.tensorparallel": "Tensor parallel", +"label.ai.tls": "TLS", +"label.ai.unhealthy": "Unhealthy", +"label.ai.update.budget": "Update budget", +"label.ai.update.deployment": "Update endpoint", +"label.ai.update.generation.profile": "Update generation profile", +"label.ai.update.guardrail.profile": "Update guardrail profile", +"label.ai.update.serving.profile": "Update serving profile", +"label.ai.upload.adapter": "Upload adapter", +"label.ai.upload.certificate": "Upload certificate", +"label.ai.usage.budgets": "Usage and budgets", +"label.ai.weight": "Weight", +"label.aiservices": "AI Services", +"label.basemodel": "Base model", +"label.customdomain": "Custom domain", +"label.deployment": "Deployment", +"label.force": "Force", +"label.input": "Requests (JSONL)", +"label.inputuri": "Input URI", +"label.model": "Model", +"label.onexceed": "When exceeded", +"label.preset": "Preset", +"label.pricetier": "Price tier", +"label.profile": "Profile", +"label.publicenabled": "Public endpoint enabled", +"label.rank": "LoRA rank", +"label.replicas": "Replicas", +"label.repoid": "Repository", +"label.revision": "Revision", +"label.servingprofile": "Serving profile", +"label.sizebytes": "Size in bytes", +"label.target": "Target", +"label.tls": "TLS", +"label.uri": "Artifact URI", +"label.visibility": "Visibility", +"message.ai.approve.model": "Approve this model for the tenant catalog? Tenants in the selected domains will be able to deploy it.", +"message.ai.cancel.batch": "Cancelling stops this batch where it is. Requests already completed are billed and their results stay available; the rest are not run.", +"message.ai.delete.adapter": "Deleting this adapter stops every request that addresses it. Requests using the base model on its own are unaffected.", +"message.ai.delete.certificate": "Deleting this certificate cannot be undone, and any private endpoint using it will stop serving HTTPS on its custom domain.", +"message.ai.delete.deployment": "Delete this endpoint? Its replicas are removed and its base URL stops answering. API keys scoped to it will be refused.", +"message.ai.delete.generation.profile": "Delete this generation profile? Any scope it is assigned to falls back to the level above it.", +"message.ai.delete.guardrail.profile": "Deleting this guardrail profile removes its checks from every scope it is assigned to, and requests there stop being screened.", +"message.ai.delete.private.endpoint": "Removing this private endpoint destroys its proxy VM. Anything calling the endpoint on this network, or on its custom domain, stops working.", +"message.ai.delete.serving.profile": "Delete this serving profile? Deployments using it keep running until their next change, then fall back to the platform default.", +"message.ai.drain.node": "Drain this node? Its replicas move to other hosts and the node VM is destroyed, not stopped — a stopped node would keep its GPUs allocated.", +"message.ai.promote.rollout": "Send all traffic to the candidate colour? The colour serving now is retired once the candidate is live.", +"message.ai.replace.certificate": "Replacing this certificate rebuilds the endpoint's proxy, which interrupts traffic: a proxy reads its certificate once, when it boots.", +"message.ai.rollback.rollout": "Send all traffic back to the colour serving now? The candidate keeps running until you delete it." } diff --git a/ui/src/config/router.js b/ui/src/config/router.js index b9c60bcd0c21..29426b9301fd 100644 --- a/ui/src/config/router.js +++ b/ui/src/config/router.js @@ -28,6 +28,7 @@ import compute from '@/config/section/compute' import storage from '@/config/section/storage' import network from '@/config/section/network' import image from '@/config/section/image' +import aiservices from '@/config/section/aiservices' import kms from '@/config/section/kms' import project from '@/config/section/project' import event from '@/config/section/event' @@ -220,6 +221,7 @@ export function asyncRouterMap () { generateRouterMap(storage), generateRouterMap(network), generateRouterMap(image), + generateRouterMap(aiservices), generateRouterMap(kms), generateRouterMap(event), generateRouterMap(project), diff --git a/ui/src/config/section/aiservices.js b/ui/src/config/section/aiservices.js new file mode 100644 index 000000000000..ca12955ce473 --- /dev/null +++ b/ui/src/config/section/aiservices.js @@ -0,0 +1,845 @@ +// 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. + +// The AI Services section (SPEC.md section 9). +// +// Declarative on purpose. CloudStack builds list views, detail views, +// search, pagination, async job notifications and role-based action +// visibility from this config, so a screen described here inherits all +// of it and behaves like every other section — which is the whole +// reason for not hand-rolling the screens. +// +// Tenant screens come first: milestone 6 is "tenant first", and a +// tenant landing on an admin list they cannot read is a bad first +// impression of the product. +// +// Every `api` below must exist in aisvc/api/commands.py; a unit test +// holds the two together, because a renamed command would otherwise +// leave a button that fails with no sign of why. + +import { defineAsyncComponent, shallowRef } from 'vue' +import store from '@/store' + +const role = () => store.getters.userInfo.roletype +const isAdmin = () => role() === 'Admin' +const isAdminOrDomainAdmin = () => ['Admin', 'DomainAdmin'].includes(role()) + +const view = (name) => + shallowRef(defineAsyncComponent(() => import(`@/views/aiservices/${name}.vue`))) + +const detailsTab = { + name: 'details', + component: shallowRef( + defineAsyncComponent(() => import('@/components/view/DetailsTab.vue')) + ) +} + +export default { + name: 'aiservices', + title: 'label.aiservices', + icon: 'experiment-outlined', + // Visible to everyone with a role: a tenant sees their catalog and + // endpoints, an admin sees those plus the operator screens. + show: () => ['Admin', 'DomainAdmin', 'User'].includes(role()), + children: [ + // -- tenant --------------------------------------------------------- + { + name: 'aimodelcatalog', + title: 'label.ai.model.catalog', + icon: 'appstore-outlined', + permission: ['listAiModels'], + resourceType: 'AiModel', + columns: () => [ + 'name', { field: 'task', customTitle: 'ai.task' }, 'size', + { field: 'license', customTitle: 'ai.license' }, + { field: 'pricetier', customTitle: 'ai.pricetier' } + ], + details: () => [ + 'id', 'name', { field: 'task', customTitle: 'ai.task' }, 'size', + { field: 'license', customTitle: 'ai.license' }, + { field: 'pricetier', customTitle: 'ai.pricetier' }, + { field: 'contextlength', customTitle: 'ai.contextlength' }, + 'description' + ], + tabs: [detailsTab], + actions: [ + { + api: 'deployAiModel', + icon: 'rocket-outlined', + label: 'label.ai.deploy.model', + dataView: true, + popup: true, + args: ['zoneid', 'name', 'replicas', 'servingprofile'] + } + ] + }, + { + name: 'aiendpoint', + title: 'label.ai.endpoints', + icon: 'api-outlined', + permission: ['listAiEndpoints'], + resourceType: 'AiEndpoint', + columns: () => { + const fields = [ + // Keyed `name` and rendered from the model, because + // AiEndpointResponse has no `name` of its own: a bare + // 'name' column drew blank, and ListView links only a + // column called `name`, so the detail view — with its API + // keys tab, its snippets tab and three actions — had no + // route to it at all. + { field: 'name', customTitle: 'ai.model', name: (record) => record.model }, + 'state', + { field: 'replicas', customTitle: 'ai.replicas' }, + { field: 'baseurl', customTitle: 'ai.baseurl' } + ] + // Only an operator benefits from the owner column; for a tenant + // every row is theirs and it is a wasted column. + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'id', 'name', { field: 'model', customTitle: 'ai.model' }, 'state', + { field: 'replicas', customTitle: 'ai.replicas' }, + { field: 'baseurl', customTitle: 'ai.baseurl' }, + { field: 'pricetier', customTitle: 'ai.pricetier' }, + 'account', 'domainpath', 'created' + ], + tabs: [ + detailsTab, + { + // A tab's name is the key *without* `label.`: CloudStack + // renders it as $t('label.' + tab.name), so a name carrying + // the prefix came out as "label.label.ai.api.keys" on the + // screen. The shared `detailsTab` is named plain `details`, + // which is why that one tab always read correctly. + name: 'ai.api.keys', + component: view('ApiKeysTab') + }, + { + name: 'ai.snippets', + component: view('SnippetsTab') + } + ], + actions: [ + { + api: 'updateAiModelDeployment', + icon: 'edit-outlined', + label: 'label.ai.update.deployment', + dataView: true, + popup: true, + args: ['replicas', 'servingprofile'] + }, + { + api: 'deleteAiModelDeployment', + icon: 'delete-outlined', + label: 'label.ai.delete.deployment', + dataView: true, + // CloudStack asks for confirmation; this is not reversible. + message: 'message.ai.delete.deployment' + } + ] + }, + { + name: 'aiplayground', + title: 'label.ai.playground', + icon: 'message-outlined', + permission: ['createAiPlaygroundSession'], + component: view('Playground'), + columns: () => [{ field: 'model', customTitle: 'ai.model' }], + details: () => [{ field: 'model', customTitle: 'ai.model' }], + actions: [] + }, + { + name: 'aigenerationprofile', + title: 'label.ai.generation.profiles', + icon: 'sliders-outlined', + permission: ['listAiGenerationProfiles'], + resourceType: 'AiGenerationProfile', + columns: () => { + const fields = ['name', 'scope', 'policy'] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => ['id', 'name', 'description', 'scope', 'policy', 'account'], + tabs: [detailsTab], + actions: [ + { + api: 'createAiGenerationProfile', + icon: 'plus-outlined', + label: 'label.ai.create.generation.profile', + listView: true, + popup: true, + args: ['name', 'params'] + }, + { + api: 'updateAiGenerationProfile', + icon: 'edit-outlined', + label: 'label.ai.update.generation.profile', + dataView: true, + popup: true, + args: ['params'] + }, + { + api: 'assignAiTuningProfile', + icon: 'link-outlined', + label: 'label.ai.assign.profile', + dataView: true, + popup: true, + args: ['profile', 'scope', 'target'] + }, + { + api: 'deleteAiGenerationProfile', + icon: 'delete-outlined', + label: 'label.ai.delete.generation.profile', + dataView: true, + message: 'message.ai.delete.generation.profile' + } + ] + }, + { + name: 'aieffectiveparameters', + title: 'label.ai.effective.parameters', + icon: 'function-outlined', + permission: ['getAiEffectiveParameters'], + // A resolved value is meaningless without the level it came from + // (SPEC.md section 6), and a plain detail view cannot show that + // pairing, so this screen is its own component. + component: view('EffectiveParameters'), + columns: () => [{ field: 'parameter', customTitle: 'ai.parameter' }, 'value', 'source'], + details: () => [ + { field: 'parameter', customTitle: 'ai.parameter' }, 'value', 'source', 'policy' + ], + actions: [] + }, + { + name: 'aiusage', + title: 'label.ai.usage.budgets', + icon: 'dollar-outlined', + permission: ['listAiUsage'], + resourceType: 'AiUsage', + columns: () => { + const fields = [ + // Keyed `name` so CloudStack links the row: ListView + // renders the way into a detail view only on a column + // called `name`, and `updateAiBudget` lives there. + { field: 'name', customTitle: 'ai.model', name: (record) => record.model }, + { field: 'inputtokens', customTitle: 'ai.inputtokens' }, + { field: 'outputtokens', customTitle: 'ai.outputtokens' }, + { field: 'gpuhours', customTitle: 'ai.gpuhours' }, + { field: 'cost', customTitle: 'ai.cost' } + ] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'account', { field: 'model', customTitle: 'ai.model' }, + { field: 'inputtokens', customTitle: 'ai.inputtokens' }, + { field: 'outputtokens', customTitle: 'ai.outputtokens' }, + { field: 'gpuhours', customTitle: 'ai.gpuhours' }, + { field: 'cost', customTitle: 'ai.cost' }, + 'currency', { field: 'recorded', customTitle: 'ai.recorded' } + ], + tabs: [ + detailsTab, + { + name: 'ai.budgets', + component: view('BudgetsTab') + } + ], + actions: [ + { + api: 'createAiBudget', + icon: 'plus-outlined', + label: 'label.ai.create.budget', + listView: true, + popup: true, + // Admin only: a tenant able to set its own budget could lift + // the limit that is blocking it. + show: isAdminOrDomainAdmin, + args: ['account', 'domain', 'monthly', 'currency', 'onexceed'] + }, + { + api: 'updateAiBudget', + icon: 'edit-outlined', + label: 'label.ai.update.budget', + dataView: true, + popup: true, + show: isAdminOrDomainAdmin, + args: ['monthly', 'currency', 'onexceed'] + } + ] + }, + + // -- tenant, v2 ----------------------------------------------------- + // + // These need no `show` of their own. CloudStack drops a route whose + // `permission` is missing from the account's listApis answer, and + // the plugin only registers the v2 commands when + // ai.services.v2.enabled is on — so on a v1 install the commands + // are absent, the routes are dropped, and these screens are not + // there. A second switch here could only disagree with that one. + { + name: 'aiadapter', + title: 'label.ai.adapters', + icon: 'deployment-unit-outlined', + permission: ['listAiAdapters'], + resourceType: 'AiAdapter', + columns: () => { + // `servedmodelname` is what a tenant actually puts in a + // request — `:` — so it earns a column over the + // adapter's own name, which addresses nothing. + const fields = [ + 'name', { field: 'basemodel', customTitle: 'ai.basemodel' }, + { field: 'servedmodelname', customTitle: 'ai.servedmodelname' }, + { field: 'rank', customTitle: 'ai.rank' } + ] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'id', 'name', { field: 'basemodel', customTitle: 'ai.basemodel' }, + { field: 'servedmodelname', customTitle: 'ai.servedmodelname' }, + { field: 'rank', customTitle: 'ai.rank' }, + { field: 'sizebytes', customTitle: 'ai.sizebytes' }, + 'shared', 'account', 'created' + ], + tabs: [detailsTab], + actions: [ + { + api: 'uploadAiAdapter', + icon: 'upload-outlined', + label: 'label.ai.upload.adapter', + listView: true, + popup: true, + args: ['name', 'basemodel', 'rank', 'sizebytes', 'files', 'uri'] + }, + { + api: 'deleteAiAdapter', + icon: 'delete-outlined', + label: 'label.ai.delete.adapter', + dataView: true, + message: 'message.ai.delete.adapter' + } + ] + }, + { + name: 'aibatch', + title: 'label.ai.batches', + icon: 'unordered-list-outlined', + permission: ['listAiBatches'], + resourceType: 'AiBatch', + columns: () => { + const fields = [ + { field: 'name', customTitle: 'ai.batch', name: (record) => record.id }, + { field: 'model', customTitle: 'ai.model' }, 'status', + { field: 'requestcount', customTitle: 'ai.requestcount' }, 'created' + ] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'id', { field: 'model', customTitle: 'ai.model' }, 'status', + { field: 'requestcount', customTitle: 'ai.requestcount' }, 'account', 'created', + { field: 'finished', customTitle: 'ai.finished' }, + { field: 'inputuri', customTitle: 'ai.inputuri' }, + { field: 'outputuri', customTitle: 'ai.outputuri' } + ], + tabs: [detailsTab], + actions: [ + { + api: 'createAiBatch', + icon: 'plus-outlined', + label: 'label.ai.create.batch', + listView: true, + popup: true, + args: ['model', 'input', 'inputuri'] + }, + { + api: 'getAiBatchResults', + icon: 'download-outlined', + label: 'label.ai.batch.results', + dataView: true + }, + { + api: 'cancelAiBatch', + icon: 'stop-outlined', + label: 'label.ai.cancel.batch', + dataView: true, + message: 'message.ai.cancel.batch' + } + ] + }, + { + name: 'aicertificate', + title: 'label.ai.certificates', + icon: 'safety-certificate-outlined', + permission: ['listAiCertificates'], + resourceType: 'AiCertificate', + // Metadata only: the engine never returns the certificate body + // and never the key, so there is nothing here to put on a screen + // that should not be on one. + columns: () => { + const fields = [ + { + field: 'name', + customTitle: 'ai.customdomain', + name: (record) => record.customdomain + }, + { field: 'expires', customTitle: 'ai.expires' }, 'fingerprint' + ] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'id', { field: 'customdomain', customTitle: 'ai.customdomain' }, 'fingerprint', + { field: 'serial', customTitle: 'ai.serial' }, + { field: 'expires', customTitle: 'ai.expires' }, 'account', + 'created' + ], + tabs: [detailsTab], + actions: [ + { + api: 'uploadAiCertificate', + icon: 'upload-outlined', + label: 'label.ai.upload.certificate', + listView: true, + popup: true, + args: ['customdomain', 'certificate', 'privatekey'] + }, + { + api: 'replaceAiCertificate', + icon: 'reload-outlined', + label: 'label.ai.replace.certificate', + dataView: true, + popup: true, + // Replacing rebuilds the proxy, which is downtime: a proxy + // fetches its material once, at boot (PROGRESS.md, m9). + message: 'message.ai.replace.certificate', + args: ['certificate', 'privatekey'] + }, + { + api: 'deleteAiCertificate', + icon: 'delete-outlined', + label: 'label.ai.delete.certificate', + dataView: true, + message: 'message.ai.delete.certificate' + } + ] + }, + { + name: 'aiprivateendpoint', + title: 'label.ai.private.endpoints', + icon: 'lock-outlined', + permission: ['listAiPrivateEndpoints'], + resourceType: 'AiPrivateEndpoint', + columns: () => { + // `exposure` is the phrase the engine builds — "private on + // net-1 as ai.acme.example". It is the one column a buyer + // checking that an endpoint really is private will read. + const fields = [ + { + field: 'name', + customTitle: 'ai.deployment', + name: (record) => record.deployment + }, + { field: 'exposure', customTitle: 'ai.exposure' }, + { field: 'customdomain', customTitle: 'ai.customdomain' }, + { field: 'tls', customTitle: 'ai.tls' } + ] + if (isAdminOrDomainAdmin()) fields.push('account') + return fields + }, + details: () => [ + 'id', { field: 'deployment', customTitle: 'ai.deployment' }, + { field: 'exposure', customTitle: 'ai.exposure' }, 'network', + { field: 'publicenabled', customTitle: 'ai.publicenabled' }, + { field: 'customdomain', customTitle: 'ai.customdomain' }, + { field: 'tls', customTitle: 'ai.tls' }, 'certificate', 'account', 'created' + ], + tabs: [detailsTab], + actions: [ + { + api: 'createAiPrivateEndpoint', + icon: 'plus-outlined', + label: 'label.ai.create.private.endpoint', + listView: true, + popup: true, + args: [ + 'deployment', 'networkid', 'publicenabled', 'customdomain', + 'tls', 'certificateid' + ] + }, + { + api: 'deleteAiPrivateEndpoint', + icon: 'delete-outlined', + label: 'label.ai.delete.private.endpoint', + dataView: true, + message: 'message.ai.delete.private.endpoint' + } + ] + }, + { + name: 'aiguardrail', + title: 'label.ai.guardrails', + icon: 'safety-outlined', + permission: ['listAiGuardrailProfiles'], + // No `show`: the engine scopes these now, so a tenant sees the + // platform profile screening them and may tighten their own + // account. What they may not do is written where it belongs — + // in aisvc/guardrails/authority.py — and refused there, with a + // message saying what they can do instead. + resourceType: 'AiGuardrailProfile', + columns: () => ['name', 'scope', { field: 'target', customTitle: 'ai.target' }], + details: () => [ + 'id', 'name', 'scope', { field: 'target', customTitle: 'ai.target' } + ], + // The checks are a tab, not a detail row: they are a named list, + // and DetailsTab prints a value rather than rendering one, so a + // list there reads "[object Object]". + tabs: [ + detailsTab, + { + name: 'ai.checks', + component: view('GuardrailChecksTab') + } + ], + actions: [ + { + api: 'createAiGuardrailProfile', + icon: 'plus-outlined', + label: 'label.ai.create.guardrail.profile', + listView: true, + popup: true, + args: ['name', 'scope', 'target', 'preset'] + }, + { + api: 'updateAiGuardrailProfile', + icon: 'edit-outlined', + label: 'label.ai.update.guardrail.profile', + dataView: true, + popup: true, + args: ['target'] + }, + { + api: 'deleteAiGuardrailProfile', + icon: 'delete-outlined', + label: 'label.ai.delete.guardrail.profile', + dataView: true, + message: 'message.ai.delete.guardrail.profile' + } + ] + }, + + // -- admin ---------------------------------------------------------- + { + name: 'aisetup', + title: 'label.ai.setup', + icon: 'tool-outlined', + permission: ['listAiSetupChecks'], + show: isAdmin, + // A wizard is a sequence, not a list of rows. + component: view('SetupWizard'), + columns: () => ['name', 'status', { field: 'detail', customTitle: 'ai.detail' }], + details: () => [ + 'name', 'status', { field: 'detail', customTitle: 'ai.detail' }, + { field: 'remedy', customTitle: 'ai.remedy' } + ], + actions: [ + { + api: 'runAiSetupSelfTest', + icon: 'experiment-outlined', + label: 'label.ai.run.self.test', + listView: true, + popup: true, + args: ['zoneid'] + }, + { + api: 'discoverAiGpuClasses', + icon: 'search-outlined', + label: 'label.ai.discover.gpu.classes', + listView: true + } + ] + }, + { + name: 'aihuggingface', + title: 'label.ai.huggingface', + icon: 'cloud-download-outlined', + permission: ['searchAiHfModels'], + show: isAdminOrDomainAdmin, + component: view('HuggingFaceBrowser'), + columns: () => [ + { field: 'name', customTitle: 'ai.repo', name: (record) => record.repo }, + { field: 'task', customTitle: 'ai.task' }, + { field: 'license', customTitle: 'ai.license' }, + { field: 'downloads', customTitle: 'ai.downloads' }, + { field: 'compatible', customTitle: 'ai.compatible' } + ], + details: () => [ + { field: 'repo', customTitle: 'ai.repo' }, + { field: 'revision', customTitle: 'ai.revision' }, + { field: 'task', customTitle: 'ai.task' }, + { field: 'license', customTitle: 'ai.license' }, 'params', + { field: 'problems', customTitle: 'ai.problems' } + ], + actions: [ + { + api: 'checkAiHfModel', + icon: 'safety-certificate-outlined', + label: 'label.ai.check.compatibility', + dataView: true, + popup: true, + args: ['repoid', 'revision'] + }, + { + api: 'mirrorAiModel', + icon: 'cloud-download-outlined', + label: 'label.ai.mirror.model', + dataView: true, + popup: true, + args: ['repoid', 'revision'] + }, + { + api: 'approveAiModel', + icon: 'check-outlined', + label: 'label.ai.approve.model', + dataView: true, + show: isAdmin, + message: 'message.ai.approve.model' + } + ] + }, + { + name: 'airegistry', + title: 'label.ai.registry', + icon: 'database-outlined', + permission: ['listAiModels'], + show: isAdminOrDomainAdmin, + resourceType: 'AiModel', + columns: () => [ + 'name', { field: 'repo', customTitle: 'ai.repo' }, + { field: 'revision', customTitle: 'ai.revision' }, + { field: 'license', customTitle: 'ai.license' }, 'sizegb', + { field: 'deployments', customTitle: 'ai.deployments' } + ], + details: () => [ + 'id', 'name', { field: 'repo', customTitle: 'ai.repo' }, + { field: 'revision', customTitle: 'ai.revision' }, + { field: 'sha256', customTitle: 'ai.sha256' }, + { field: 'license', customTitle: 'ai.license' }, 'sizegb', + { field: 'task', customTitle: 'ai.task' }, + { field: 'published', customTitle: 'ai.published' }, + { field: 'deployments', customTitle: 'ai.deployments' } + ], + tabs: [ + detailsTab, + { + // v2. The tab is always declared; `runAiModelEvaluation` and + // `listAiEvaluations` are not registered on a v1 install, so + // the action is hidden by CloudStack and the tab reports + // nothing to show. + name: 'ai.evaluations', + component: view('EvaluationsTab') + } + ], + actions: [ + { + api: 'publishAiModel', + icon: 'global-outlined', + label: 'label.ai.publish.model', + dataView: true, + popup: true, + args: ['pricetier', 'visibility'] + }, + { + api: 'runAiModelEvaluation', + icon: 'experiment-outlined', + label: 'label.ai.run.evaluation', + dataView: true, + popup: true, + // Root admin: the gate exists to stop a bad revision being + // published, so the person who runs it is the one who can + // override it (SPEC.md section 8). + show: isAdmin, + args: ['model', 'revision'] + } + ] + }, + { + name: 'aicapacity', + title: 'label.ai.gpu.capacity', + icon: 'hdd-outlined', + permission: ['listAiGpuCapacity'], + show: isAdmin, + // SPEC.md section 9 asks for a heatmap by zone and class, which + // is not a table. + component: view('GpuCapacity'), + columns: () => [ + 'zone', { field: 'gpuclass', customTitle: 'ai.gpuclass' }, 'total', 'allocated', 'free', + { field: 'unhealthy', customTitle: 'ai.unhealthy' } + ], + details: () => [ + 'zone', { field: 'gpuclass', customTitle: 'ai.gpuclass' }, + { field: 'hosttag', customTitle: 'ai.hosttag' }, 'total', 'allocated', 'free', + { field: 'unhealthy', customTitle: 'ai.unhealthy' }, + { field: 'nodes', customTitle: 'ai.nodes' } + ], + actions: [] + }, + { + name: 'aifleet', + title: 'label.ai.fleet.health', + icon: 'cluster-outlined', + permission: ['listAiGpuCapacity'], + show: isAdmin, + component: view('FleetHealth'), + columns: () => [ + { field: 'name', customTitle: 'ai.host', name: (record) => record.host }, + 'template', 'driver', 'state', { field: 'drift', customTitle: 'ai.drift' } + ], + details: () => [ + 'host', 'template', 'driver', 'state', { field: 'drift', customTitle: 'ai.drift' }, + { field: 'nodes', customTitle: 'ai.nodes' } + ], + actions: [ + { + api: 'drainAiNode', + icon: 'logout-outlined', + label: 'label.ai.drain.node', + dataView: true, + popup: true, + // Destroy, not stop: a stopped node keeps its GPU allocated + // (ADR-0003), so the confirmation has to say so. + message: 'message.ai.drain.node', + args: ['force'] + } + ] + }, + { + name: 'airollout', + title: 'label.ai.rollouts', + icon: 'swap-outlined', + permission: ['listAiModelDeployments'], + show: isAdminOrDomainAdmin, + resourceType: 'AiDeployment', + columns: () => [ + // Same as endpoints: AiDeploymentResponse carries no `name`, + // so the row had nothing to link and promote/rollback were + // unreachable. + { field: 'name', customTitle: 'ai.model', name: (record) => record.model }, + { field: 'livecolour', customTitle: 'ai.livecolour' }, + { field: 'candidate', customTitle: 'ai.candidate' }, + { field: 'weight', customTitle: 'ai.weight' }, 'state' + ], + details: () => [ + 'id', 'name', { field: 'model', customTitle: 'ai.model' }, + { field: 'livecolour', customTitle: 'ai.livecolour' }, + { field: 'candidate', customTitle: 'ai.candidate' }, + { field: 'weight', customTitle: 'ai.weight' }, 'state', + { field: 'spechash', customTitle: 'ai.spechash' } + ], + tabs: [detailsTab], + actions: [ + { + api: 'promoteAiRollout', + icon: 'check-circle-outlined', + label: 'label.ai.promote.rollout', + dataView: true, + message: 'message.ai.promote.rollout' + }, + { + api: 'rollbackAiRollout', + icon: 'rollback-outlined', + label: 'label.ai.rollback.rollout', + dataView: true, + message: 'message.ai.rollback.rollout' + } + ] + }, + { + name: 'aiservingprofile', + title: 'label.ai.serving.profiles', + icon: 'control-outlined', + permission: ['listAiServingProfiles'], + // Serving profiles size vLLM against the hardware; a tenant + // changing one could take a GPU host down (SPEC.md section 7). + show: isAdmin, + resourceType: 'AiServingProfile', + columns: () => [ + 'name', { field: 'maxnumseqs', customTitle: 'ai.maxnumseqs' }, + { field: 'gpumemoryutilization', customTitle: 'ai.gpumemoryutilization' }, + { field: 'maxmodellen', customTitle: 'ai.maxmodellen' } + ], + details: () => [ + 'id', 'name', 'description', { field: 'maxnumseqs', customTitle: 'ai.maxnumseqs' }, + { field: 'gpumemoryutilization', customTitle: 'ai.gpumemoryutilization' }, + { field: 'maxmodellen', customTitle: 'ai.maxmodellen' }, + { field: 'tensorparallel', customTitle: 'ai.tensorparallel' } + ], + tabs: [detailsTab], + actions: [ + { + api: 'createAiServingProfile', + icon: 'plus-outlined', + label: 'label.ai.create.serving.profile', + listView: true, + popup: true, + args: ['name', 'params'] + }, + { + api: 'updateAiServingProfile', + icon: 'edit-outlined', + label: 'label.ai.update.serving.profile', + dataView: true, + popup: true, + args: ['params'] + }, + { + api: 'deleteAiServingProfile', + icon: 'delete-outlined', + label: 'label.ai.delete.serving.profile', + dataView: true, + message: 'message.ai.delete.serving.profile' + } + ] + }, + { + name: 'aiactivity', + title: 'label.ai.activity', + icon: 'history-outlined', + permission: ['listAiReconcilerRuns'], + show: isAdminOrDomainAdmin, + resourceType: 'AiReconcilerRun', + columns: () => [ + 'id', 'zone', 'status', 'actions', 'started', + { field: 'finished', customTitle: 'ai.finished' } + ], + details: () => [ + 'id', 'zone', 'status', 'actions', 'started', + { field: 'finished', customTitle: 'ai.finished' }, 'error' + ], + tabs: [ + detailsTab, + { + name: 'ai.run.actions', + component: view('RunActionsTab') + } + ], + actions: [] + } + ] +} diff --git a/ui/src/utils/capacity.js b/ui/src/utils/capacity.js new file mode 100644 index 000000000000..5e7fd4c3fffa --- /dev/null +++ b/ui/src/utils/capacity.js @@ -0,0 +1,92 @@ +// 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. +// The GPU capacity heatmap (SPEC.md section 9). +// +// "Heatmap by zone and class: allocated, free, unhealthy, quarantined." +// The point of a heatmap is that an operator takes it in at a glance, +// so the status a cell gets is what decides its colour — and broken +// hardware has to win over a merely busy class, or a failing GPU hides +// behind a green cell. + +// What CloudStack sends, which is not what this file used to read. +// A response field is serialised under its lower-cased name, so the +// engine's `gpus_total` arrives as `gpustotal` — and `allocated` and +// `unhealthy` are not sent at all. They are differences, derived here +// so the arithmetic lives in one place. +// +// Reading the wrong names was silent: every cell took `undefined` for +// its counts, which made utilisation 0 and the status `healthy`, so a +// zone with every GPU allocated and a dead node in it drew the same +// green cell as an idle one. +function countsOf (capacity) { + const total = capacity.gpustotal ?? 0 + const free = capacity.gpusfree ?? 0 + const nodes = capacity.nodestotal ?? 0 + const healthy = capacity.nodeshealthy ?? 0 + + return { + total, + free, + allocated: Math.max(total - free, 0), + unhealthy: Math.max(nodes - healthy, 0) + } +} + +/** Fraction of a class's GPUs that are allocated, 0 to 1. */ +function utilisationOf (counts) { + // A declared class whose hosts are not tagged yet has no GPUs at all. + // Dividing by zero here puts NaN% on the operator's first screen. + if (!counts.total) return 0 + return counts.allocated / counts.total +} + +export function cellFor (capacity) { + const counts = countsOf(capacity) + const utilisation = utilisationOf(counts) + + let status = 'healthy' + if (counts.unhealthy > 0) { + // Outranks everything: a node in this state is not coming back + // without a drain, and a quiet class should not hide it. + status = 'unhealthy' + } else if (counts.free === 0 && counts.total > 0) { + status = 'exhausted' + } else if (utilisation >= 0.9) { + status = 'tight' + } + + return { + zone: capacity.zone, + gpuclass: capacity.gpuclass, + ...counts, + utilisation, + status + } +} + +/** One row per zone, one cell per GPU class, in a stable order. */ +export function heatmapRows (capacities) { + const zones = new Map() + for (const capacity of capacities) { + if (!zones.has(capacity.zone)) zones.set(capacity.zone, []) + zones.get(capacity.zone).push(cellFor(capacity)) + } + return [...zones.entries()] + .sort(([a], [b]) => a.localeCompare(b)) + .map(([zone, cells]) => ({ + zone, + cells: cells.sort((a, b) => a.gpuclass.localeCompare(b.gpuclass)) + })) +} diff --git a/ui/src/utils/errors.js b/ui/src/utils/errors.js new file mode 100644 index 000000000000..9ea6b7c0ba14 --- /dev/null +++ b/ui/src/utils/errors.js @@ -0,0 +1,44 @@ +// 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. + +// Why a screen could not load, in the engine's own words. +// +// The engine answers in RFC 9457 problem JSON so its caller can explain +// itself, the plugin appends that detail to the status, and CloudStack +// carries it to the browser as `errortext`. All of that is wasted if the +// screen reads the wrong field: axios's own `message` is "Request failed +// with status code 534", which names no remedy at all. +// +// CloudStack wraps every answer in a key named after the command — +// {"listaigpucapacityresponse": {"errorcode": 534, "errortext": "..."}} — +// refusals included, so the sentence is one level deeper than a reader +// expects. The wrapper key is not worth reconstructing from the command +// name: a refusal before dispatch comes back under "errorresponse" +// instead, so the only reliable rule is to look inside whatever single +// wrapper is there. +export function engineReason (problem) { + const data = problem?.response?.data + + if (data && typeof data === 'object') { + if (typeof data.errortext === 'string' && data.errortext) return data.errortext + + for (const wrapped of Object.values(data)) { + const text = wrapped?.errortext + if (typeof text === 'string' && text) return text + } + } + + return problem?.message ?? '' +} diff --git a/ui/src/utils/profiles.js b/ui/src/utils/profiles.js new file mode 100644 index 000000000000..1d235503a9bb --- /dev/null +++ b/ui/src/utils/profiles.js @@ -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. +// Showing resolved generation parameters (SPEC.md section 6). +// +// A resolved value on its own tells a tenant nothing: the useful +// question is always "why is it that, and can I change it". So every +// value is shown with the level it came from and whether it is open to +// them — which is exactly what getAiEffectiveParameters returns. + +const LEVELS = { + platform: 'Platform default', + model: 'Model default', + domain: 'Domain', + account: 'Account', + deployment: 'Endpoint', + apikey: 'API key', + request: 'Request' +} + +export function sourceLabel (level) { + // An unknown level is shown as-is rather than blanked: a new level + // added to the engine should look odd here, not disappear. + return LEVELS[level] ?? level +} + +export function describeParameter (parameter) { + const locked = parameter.policy === 'locked' + return { + name: parameter.name, + value: parameter.value, + source: sourceLabel(parameter.source), + policy: parameter.policy, + locked, + // `clamp` still lets a tenant choose, within the bounds the level + // above set; only `locked` takes the choice away. + editable: !locked + } +} diff --git a/ui/src/utils/setup.js b/ui/src/utils/setup.js new file mode 100644 index 000000000000..238fccdf9438 --- /dev/null +++ b/ui/src/utils/setup.js @@ -0,0 +1,42 @@ +// 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. +// The setup wizard's checks (SPEC.md sections 7 and 14). +// +// Section 14's first criterion is that a new zone reaches a passing +// self-test using only the wizard, so the screen has to be usable on a +// zone where most things are not configured yet. + +const STATUSES = ['pass', 'warn', 'fail', 'skipped'] + +export function groupChecks (checks) { + // Every group exists even when empty, so the template can render them + // unconditionally instead of guarding each one. + const grouped = Object.fromEntries(STATUSES.map((status) => [status, []])) + for (const check of checks) { + if (grouped[check.status]) grouped[check.status].push(check) + } + return grouped +} + +/** + * Whether the operator may move on. + * + * Only a failure blocks. A warning is worth saying and not worth + * stopping for, and `skipped` is the normal state of a zone that has + * not been observed yet — which is every zone on its first run. + */ +export function canProceed (checks) { + return !checks.some((check) => check.status === 'fail') +} diff --git a/ui/src/views/aiservices/ApiKeysTab.vue b/ui/src/views/aiservices/ApiKeysTab.vue new file mode 100644 index 000000000000..5b57c15d4c19 --- /dev/null +++ b/ui/src/views/aiservices/ApiKeysTab.vue @@ -0,0 +1,193 @@ + + + + + diff --git a/ui/src/views/aiservices/BudgetsTab.vue b/ui/src/views/aiservices/BudgetsTab.vue new file mode 100644 index 000000000000..a7a0357ee68b --- /dev/null +++ b/ui/src/views/aiservices/BudgetsTab.vue @@ -0,0 +1,113 @@ + + + + + diff --git a/ui/src/views/aiservices/EffectiveParameters.vue b/ui/src/views/aiservices/EffectiveParameters.vue new file mode 100644 index 000000000000..9c7afcfb7808 --- /dev/null +++ b/ui/src/views/aiservices/EffectiveParameters.vue @@ -0,0 +1,119 @@ + + + + + diff --git a/ui/src/views/aiservices/EvaluationsTab.vue b/ui/src/views/aiservices/EvaluationsTab.vue new file mode 100644 index 000000000000..4b7b36efa5eb --- /dev/null +++ b/ui/src/views/aiservices/EvaluationsTab.vue @@ -0,0 +1,112 @@ + + + + + diff --git a/ui/src/views/aiservices/FleetHealth.vue b/ui/src/views/aiservices/FleetHealth.vue new file mode 100644 index 000000000000..3ac600be3055 --- /dev/null +++ b/ui/src/views/aiservices/FleetHealth.vue @@ -0,0 +1,102 @@ + + + + + diff --git a/ui/src/views/aiservices/GpuCapacity.vue b/ui/src/views/aiservices/GpuCapacity.vue new file mode 100644 index 000000000000..1a1943e4a98c --- /dev/null +++ b/ui/src/views/aiservices/GpuCapacity.vue @@ -0,0 +1,99 @@ + + + + + diff --git a/ui/src/views/aiservices/GuardrailChecksTab.vue b/ui/src/views/aiservices/GuardrailChecksTab.vue new file mode 100644 index 000000000000..5c92f368691e --- /dev/null +++ b/ui/src/views/aiservices/GuardrailChecksTab.vue @@ -0,0 +1,66 @@ + + + + + diff --git a/ui/src/views/aiservices/HuggingFaceBrowser.vue b/ui/src/views/aiservices/HuggingFaceBrowser.vue new file mode 100644 index 000000000000..caf451c99942 --- /dev/null +++ b/ui/src/views/aiservices/HuggingFaceBrowser.vue @@ -0,0 +1,108 @@ + + + + + diff --git a/ui/src/views/aiservices/Playground.vue b/ui/src/views/aiservices/Playground.vue new file mode 100644 index 000000000000..bb4dd7b437ec --- /dev/null +++ b/ui/src/views/aiservices/Playground.vue @@ -0,0 +1,144 @@ + + + + + diff --git a/ui/src/views/aiservices/RunActionsTab.vue b/ui/src/views/aiservices/RunActionsTab.vue new file mode 100644 index 000000000000..bb1f2820e086 --- /dev/null +++ b/ui/src/views/aiservices/RunActionsTab.vue @@ -0,0 +1,82 @@ + + + + + diff --git a/ui/src/views/aiservices/SetupWizard.vue b/ui/src/views/aiservices/SetupWizard.vue new file mode 100644 index 000000000000..5d929be6499d --- /dev/null +++ b/ui/src/views/aiservices/SetupWizard.vue @@ -0,0 +1,106 @@ + + + + + diff --git a/ui/src/views/aiservices/SnippetsTab.vue b/ui/src/views/aiservices/SnippetsTab.vue new file mode 100644 index 000000000000..a2de44151fc6 --- /dev/null +++ b/ui/src/views/aiservices/SnippetsTab.vue @@ -0,0 +1,54 @@ + + + + +