feat(mlx): add the modeldetailedinfo call (#874)

* feat(mlx): add the modeldetailedinfo call

* fix(SRC-5281): drop call that was removed (#873)

fix(SRC-5281)!: drop call that was removed

* fix: double status interface

* fix(test): add test for modeldetailedinfo

* fix: lint fix interface

* fix: add point

---------

Co-authored-by: Tahar Mustapha <[email protected]>
Co-authored-by: JTangCoveo <[email protected]>

src/resources/MachineLearning/MachineLearning.ts

@@ -2,15 +2,16 @@ import API from '../../APICore.js';
 import Resource from '../Resource.js';
 import CaseClassificationConfiguration from './CaseClassificationConfiguration/CaseClassificationConfiguration.js';
 import DNEConfiguration from './DNEConfiguration/DNEConfiguration.js';
-import SmartSnippetsConfiguration from './SmartSnippetsConfiguration/SmartSnippetsConfiguration.js';
+import IAPRConfiguration from './IAPRConfiguration/IAPRConfiguration.js';
 import {MLModelCreated, RegistrationModel} from './MachineLearningInterfaces.js';
+import ModelDetailedInfo from './ModelDetailedInfo/ModelDetailedInfo.js';
+import ModelListing from './ModelListing/ModelListing.js';
 import Models from './Models/Models.js';
 import PQSConfiguration from './PQSConfiguration/PQSConfiguration.js';
-import UserActionHistoryConfiguration from './UserActionHistoryConfiguration/UserActionHistoryConfiguration.js';
-import IAPRConfiguration from './IAPRConfiguration/IAPRConfiguration.js';
-import ModelListing from './ModelListing/ModelListing.js';
 import RelevanceGenerativeAnsweringConfiguration from './RGAConfiguration/RelevanceGenerativeAnsweringConfiguration.js';
 import SemanticEncoderConfiguration from './SemanticEncoderConfiguration/SemanticEncoderConfiguration.js';
+import SmartSnippetsConfiguration from './SmartSnippetsConfiguration/SmartSnippetsConfiguration.js';
+import UserActionHistoryConfiguration from './UserActionHistoryConfiguration/UserActionHistoryConfiguration.js';
 
 export default class MachineLearning extends Resource {
     static baseUrl = `/rest/organizations/${API.orgPlaceholder}/machinelearning`;
@@ -25,6 +26,7 @@ export default class MachineLearning extends Resource {
     modelListing: ModelListing;
     relevanceGenerativeAnsweringConfig: RelevanceGenerativeAnsweringConfiguration;
     semanticEncoderConfig: SemanticEncoderConfiguration;
+    modelDetailedInfo: ModelDetailedInfo;
 
     constructor(
         protected api: API,
@@ -42,6 +44,7 @@ export default class MachineLearning extends Resource {
         this.modelListing = new ModelListing(api, serverlessApi);
         this.relevanceGenerativeAnsweringConfig = new RelevanceGenerativeAnsweringConfiguration(api, serverlessApi);
         this.semanticEncoderConfig = new SemanticEncoderConfiguration(api, serverlessApi);
+        this.modelDetailedInfo = new ModelDetailedInfo(api, serverlessApi);
     }
 
     register(registration: RegistrationModel) {

src/resources/MachineLearning/MachineLearningInterfaces.ts

@@ -103,3 +103,15 @@ export interface MLModelCreated extends New<MLModel> {
     startTime?: number;
     resourceId?: string;
 }
+
+export enum MLModelStatus {
+    ARCHIVED = 'ARCHIVED',
+    SOON_TO_BE_ARCHIVED = 'SOON_TO_BE_ARCHIVED',
+    BUILD_IN_PROGRESS = 'BUILD_IN_PROGRESS',
+    ERROR = 'ERROR',
+    ERROR_INTERNAL = 'ERROR_INTERNAL',
+    LIMITED = 'LIMITED',
+    NOT_ASSOCIATED = 'NOT_ASSOCIATED',
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+}

src/resources/MachineLearning/ModelDetailedInfo/ModelDetailedInfo.ts

@@ -0,0 +1,11 @@
+import API from '../../../APICore.js';
+import Resource from '../../Resource.js';
+import {ModelWithDetails} from './ModelDetailedInfoInterfaces.js';
+
+export default class ModelDetailedInfo extends Resource {
+    static baseUrl = `/rest/organizations/${API.orgPlaceholder}/machinelearning/configuration/modeldetailedinfo`;
+
+    get(modelId: string) {
+        return this.api.get<ModelWithDetails>(`${ModelDetailedInfo.baseUrl}/${modelId}`);
+    }
+}

src/resources/MachineLearning/ModelDetailedInfo/ModelDetailedInfoInterfaces.ts

@@ -0,0 +1,99 @@
+import {MLModelStatus} from '../MachineLearningInterfaces.js';
+import {ModelDetails} from './details/ModelDetails.js';
+
+export interface ModelAssociation {
+    /**
+     * The unique identifier of the query pipeline to which the model is associated.
+     * @example 38b08160-d7d4-4626-8e03-53587c23415d
+     */
+    parentId: string;
+    /**
+     * The unique identifier of the model association.
+     * @example 917af358-13fd-4c8e-94af-7cf649bddc48
+     */
+    id: string;
+    /**
+     * The name of the query pipeline or case assist configuration the model is associated with.
+     * @example association name
+     */
+    name: string;
+    /**
+     * The type of the association.
+     * @example QUERY_PIPELINE
+     */
+    associationType: 'QUERY_PIPELINE' | 'CASE_ASSIST';
+}
+
+export interface ModelIssues {
+    /**
+     * A description of an error or limitation present in the model.
+     */
+    description: string;
+    /**
+     * The recommended action to perform to resolve the error or limitation.
+     */
+    troubleshoot: string;
+}
+
+export interface ModelStatusInfo {
+    /**
+     * The status of the model.
+     * @example ACTIVE
+     */
+    modelStatus: MLModelStatus;
+    /**
+     * The remaining days until the model is archived.
+     * @example 2
+     */
+    daysUntilArchival: number;
+}
+
+export interface ModelWithDetails {
+    /**
+     * The id of the engine.
+     * @Example topclicks
+     */
+    engineId: string;
+    /**
+     * The unique identifier of the target machine learning model.
+     * @example My_Model_ID
+     */
+    modelId: string;
+    /**
+     * The name of the model configuration.
+     * @example My model
+     */
+    modelDisplayName: string;
+    /**
+     * The associations related to this model.
+     * @example [{
+     *    "parentId": "38b08160-d7d4-4626-8e03-53587c23415d",
+     *    "id": "917af358-13fd-4c8e-94af-7cf649bddc48",
+     *    "name": "test pipeline",
+     *    "associationType": "QUERY_PIPELINE"
+     * }]
+     */
+    modelAssociations: ModelAssociation[];
+    /**
+     * The date and time the model was last updated.
+     * @example 1691762520000
+     */
+    estimatedPreviousModelUpdateTime: number;
+    /**
+     * The date and time the model is scheduled to start its next update.
+     * @example 1691762520000
+     */
+    nextModelUpdateTime: number;
+    /**
+     * The description and troubleshooting messages for a model error or limitation.
+     */
+    modelIssues: ModelIssues[];
+    /**
+     * The detailed information about the model.
+     */
+    modelDetails?: ModelDetails;
+    /**
+     * The current status of the model.
+     */
+    modelStatusInfo: ModelStatusInfo;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetails.ts

@@ -0,0 +1,20 @@
+import {ModelDetailsBuildingStats} from './ModelDetailsBuildingStats.js';
+import {ModelDetailsLanguages} from './ModelDetailsLanguages.js';
+import {ModelDetailsSubModels} from './ModelDetailsSubModels.js';
+
+export interface ModelDetails {
+    possibleRecommendations?: number;
+    totalQueries?: number;
+    recommendationsPerLanguage?: Map<string, number>;
+    userContextFields?: string[];
+    contentIDKeys?: string[];
+    candidatesPerFilters?: Map<string, number>;
+    contextCandidateExamples?: Map<string, string[]>;
+    languages?: Map<string, ModelDetailsLanguages>;
+    candidateExamples?: Map<string, string[]>;
+    candidatesPerLanguages?: Map<string, number>;
+    minClickCountPerLang?: Map<string, number>;
+    subModels?: {[key: string]: ModelDetailsSubModels};
+    candidates?: number;
+    modelDetailedBuildingStats?: ModelDetailsBuildingStats;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetailsBuildingStats.ts

@@ -0,0 +1,31 @@
+import {ModelDetailsCommerceEvents} from './ModelDetailsCommerceEvents.js';
+import {ModelDetailsStatsPerSource} from './ModelDetailsStatsPerSource.js';
+
+export interface ModelDetailsBuildingStats {
+    documentWithSnippetRatio?: number;
+    headerCount?: number;
+    snippetCount?: number;
+    meanSnippetLength?: number;
+    documentCount?: number;
+    documentWithSnippetCount?: number;
+    searchEventCount?: number;
+    clickEventCount?: number;
+    viewEventCount?: number;
+    customEventCount?: number;
+    segmentedVisitsCount?: number;
+    searchCount?: number;
+    clickCount?: number;
+    viewCount?: number;
+    visitsCount?: number;
+    facetSelectEventCount?: number;
+    snippetsPerDocument?: {
+        min?: number;
+        max?: number;
+        mean?: number;
+    };
+    invalidHtmlDocumentCount?: number;
+    documentWithoutIdCount?: number;
+    documentWithDuplicatedIdCount?: number;
+    commerceEventCounts?: ModelDetailsCommerceEvents;
+    modelDetailedStatsPerSource?: ModelDetailsStatsPerSource[];
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetailsCommerceEvents.ts

@@ -0,0 +1,6 @@
+export interface ModelDetailsCommerceEvents {
+    removeFromCart?: number;
+    addToCart?: number;
+    addPurchase?: number;
+    detailView?: number;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetailsLanguages.ts

@@ -0,0 +1,8 @@
+export interface ModelDetailsLanguages {
+    queries?: number;
+    words?: number;
+    stopwords?: number;
+    topfacets?: string[];
+    contextKeysToDocuments?: Map<string, number>;
+    docPerFilters?: Map<string, number>;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetailsStatsPerSource.ts

@@ -0,0 +1,7 @@
+export interface ModelDetailsStatsPerSource {
+    sourceName: string;
+    documentCount: number;
+    invalidHtmlDocumentCount: number;
+    documentWithoutIdCount: number;
+    documentWithDuplicatedIdCount: number;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/ModelDetailsSubModels.ts

@@ -0,0 +1,5 @@
+export interface ModelDetailsSubModels {
+    numOfItems?: number;
+    candidates?: string[] | string[][];
+    numOfUsers?: number;
+}

src/resources/MachineLearning/ModelDetailedInfo/details/index.ts

@@ -0,0 +1,6 @@
+export * from './ModelDetails.js';
+export * from './ModelDetailsBuildingStats.js';
+export * from './ModelDetailsCommerceEvents.js';
+export * from './ModelDetailsLanguages.js';
+export * from './ModelDetailsStatsPerSource.js';
+export * from './ModelDetailsSubModels.js';

src/resources/MachineLearning/ModelDetailedInfo/index.ts

@@ -0,0 +1,3 @@
+export * from './details/index.js';
+export * from './ModelDetailedInfo.js';
+export * from './ModelDetailedInfoInterfaces.js';

src/resources/MachineLearning/ModelDetailedInfo/tests/ModelDetailedInfo.spec.ts

@@ -0,0 +1,25 @@
+import API from '../../../../APICore.js';
+import ModelDetailedInfo from '../ModelDetailedInfo.js';
+
+jest.mock('../../../../APICore.js');
+
+describe('ModelDetailedInfo', () => {
+    let modelDetailedConfig: ModelDetailedInfo;
+    const api = new API({accessToken: 'some-token'});
+    const serverlessApi = new API({accessToken: 'some-token'});
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        modelDetailedConfig = new ModelDetailedInfo(api, serverlessApi);
+    });
+
+    describe('get', () => {
+        it('should make a GET call to the specific ModelDetailedInfo url', async () => {
+            const modelId = '🦆';
+            await modelDetailedConfig.get(modelId);
+
+            expect(api.get).toHaveBeenCalledTimes(1);
+            expect(api.get).toHaveBeenCalledWith(`${ModelDetailedInfo.baseUrl}/${modelId}`);
+        });
+    });
+});

src/resources/MachineLearning/ModelListing/ModelListingInterfaces.ts

@@ -1,3 +1,5 @@
+import {MLModelStatus} from '../MachineLearningInterfaces.js';
+
 export interface MLListingModel {
     /**
      * The model display name in the Coveo Administration console.
@@ -51,16 +53,7 @@ export interface MLModelStatusInfo {
      * The status of the model.
      * @Example `ACTIVE`
      */
-    modelStatus:
-        | 'ARCHIVED'
-        | 'SOON_TO_BE_ARCHIVED'
-        | 'BUILD_IN_PROGRESS'
-        | 'ERROR'
-        | 'ERROR_INTERNAL'
-        | 'LIMITED'
-        | 'NOT_ASSOCIATED'
-        | 'ACTIVE'
-        | 'INACTIVE';
+    modelStatus: MLModelStatus;
     /**
      * The remaining days until the model is archived.
      * @Example `4`

src/resources/MachineLearning/index.ts

@@ -1,15 +1,16 @@
+export * from './CaseClassificationConfiguration/index.js';
+export * from './DNEConfiguration/index.js';
+export * from './DocumentInterfaces.js';
+export * from './FilterConditions.js';
+export * from './IAPRConfiguration/index.js';
 export * from './MachineLearning.js';
 export * from './MachineLearningInterfaces.js';
-export * from './FilterConditions.js';
-export * from './DocumentInterfaces.js';
-export * from './Models/index.js';
+export * from './ModelDetailedInfo/index.js';
 export * from './ModelInformation/index.js';
 export * from './ModelListing/index.js';
-export * from './DNEConfiguration/index.js';
-export * from './CaseClassificationConfiguration/index.js';
-export * from './SmartSnippetsConfiguration/index.js';
+export * from './Models/index.js';
 export * from './PQSConfiguration/index.js';
+export * from './RGAConfiguration/index.js';
 export * from './SemanticEncoderConfiguration/index.js';
-export * from './IAPRConfiguration/index.js';
+export * from './SmartSnippetsConfiguration/index.js';
 export * from './UserActionHistoryConfiguration/index.js';
-export * from './RGAConfiguration/index.js';

src/resources/MachineLearning/tests/MachineLearning.spec.ts

@@ -4,6 +4,7 @@ import DNEConfiguration from '../DNEConfiguration/DNEConfiguration.js';
 import IAPRConfiguration from '../IAPRConfiguration/IAPRConfiguration.js';
 import MachineLearning from '../MachineLearning.js';
 import {RegistrationModel} from '../MachineLearningInterfaces.js';
+import ModelDetailedInfo from '../ModelDetailedInfo/ModelDetailedInfo.js';
 import Models from '../Models/Models.js';
 import PQSConfiguration from '../PQSConfiguration/PQSConfiguration.js';
 import SmartSnippetsConfiguration from '../SmartSnippetsConfiguration/SmartSnippetsConfiguration.js';
@@ -66,4 +67,9 @@ describe('MachineLearning', () => {
         expect(ml.iaprConfig).toBeDefined();
         expect(ml.iaprConfig).toBeInstanceOf(IAPRConfiguration);
     });
+
+    it('should register the modelDetailedInfo resource', () => {
+        expect(ml.modelDetailedInfo).toBeDefined();
+        expect(ml.modelDetailedInfo).toBeInstanceOf(ModelDetailedInfo);
+    });
 });