mbd-studio-sdk 2.1.2 → 2.2.0

package/V1/ranking/Ranking.js

@@ -1,55 +1,14 @@
-/**
- * Ranking client for MBD Studio SDK.
- * Fluent API: methods return the instance for chaining.
- * Rank items (candidates) with sort, diversity, and limits-by-field.
- */
-
 export class Ranking {
-  /** @type {string} */
-  _url;
-
-  /** @type {string} */
-  _apiKey;
-
-  /** @type {Array} */
   _candidates = [];
-
-  /** @type {string} */
   _sortMethod = 'sort';
-
-  /** @type {{ fields?: string[], direction?: string[] } | Array<{ field: string, weight: number }> | Array<{ field: string, direction: string, percentage: number }> | null} */
   _sortParams = null;
-
-  /** @type {string | null} */
   _diversityMethod = null;
-
-  /** @type {{ fields?: string[] } | { lambda?: number, horizon?: number } | null} */
   _diversityParams = null;
-
-  /** @type {boolean} */
   _limitsByFieldEnabled = false;
-
-  /** @type {number} */
   _everyN = 10;
-
-  /** @type {Array<{ field: string, limit: number }>} */
   _limitRules = [];
-
-  /** @type {{ endpoint: string, payload: object } | null} */
   lastCall = null;
-
-  /** @type {object | null} */
   lastResult = null;
-
-  /**
-   * @param {Object} options
-   * @param {string} options.url - Ranking service base URL
-   * @param {string} options.apiKey - API key for authentication
-   * @param {Array} [options.candidates] - Items to rank (hits with _id, _features, _scores, _source)
-   * @param {string} [options.origin='sdk'] - origin sent in backend call payloads
-   * @param {function(string): void} [options.log] - Optional override for log()
-   * @param {function(*): void} [options.show] - Optional override for show()
-   */
   constructor(options) {
     if (!options || typeof options !== 'object') {
       throw new Error('Ranking: options object is required');
@@ -68,23 +27,12 @@ export class Ranking {
     this._show = typeof show === 'function' ? show : console.log.bind(console);
     this._candidates = candidates;
   }
-
-  /**
-   * Return the endpoint path for the ranking feed.
-   * @returns {string}
-   */
   getEndpoint() {
     return '/ranking/feed';
   }
-
-  /**
-   * Collect useful field names from sort, diversity, and limits config.
-   * @private
-   */
   _getUsefulFieldsAndNeedEmbedding() {
     const useful = new Set();
     let needEmbedding = false;
-
     if (this._sortParams) {
       if (this._sortMethod === 'sort' && Array.isArray(this._sortParams.fields)) {
         this._sortParams.fields.forEach((f) => useful.add(f));
@@ -99,24 +47,15 @@ export class Ranking {
     if (this._diversityMethod === 'fields' && this._diversityParams?.fields) {
       this._diversityParams.fields.forEach((f) => useful.add(f));
     }
-    if (this._diversityMethod === 'semantic') {
-      needEmbedding = true;
-    }
+    if (this._diversityMethod === 'semantic') needEmbedding = true;
     if (this._limitsByFieldEnabled && this._limitRules.length > 0) {
       this._limitRules.forEach((r) => r.field && useful.add(r.field));
     }
-
     return { usefulFields: useful, needEmbedding };
   }
-
-  /**
-   * Build the request payload: items from candidates plus sort, diversity, limits_by_field.
-   * @returns {object}
-   */
   getPayload() {
     const { usefulFields, needEmbedding } = this._getUsefulFieldsAndNeedEmbedding();
     const hits = this._candidates || [];
-
     const items = hits.map((hit) => {
       const item = { item_id: hit._id };
       for (const key of usefulFields) {
@@ -125,31 +64,20 @@ export class Ranking {
       }
       if (needEmbedding) {
         let embed = hit._source?.item_sem_embed2;
-        if (!embed || !Array.isArray(embed)) {
-          embed = hit._source?.text_vector;
-        }
+        if (!embed || !Array.isArray(embed)) embed = hit._source?.text_vector;
         if (embed) item.embed = embed;
       }
       return item;
     });
-
     const payload = { origin: this._origin, items };
-
     const sortConfig = this._buildSortConfig();
     if (sortConfig) payload.sort = sortConfig;
-
     const diversityConfig = this._buildDiversityConfig();
     if (diversityConfig) payload.diversity = diversityConfig;
-
     const limitsByFieldConfig = this._buildLimitsByFieldConfig();
     if (limitsByFieldConfig) payload.limits_by_field = limitsByFieldConfig;
-
     return payload;
   }
-
-  /**
-   * @private
-   */
   _buildSortConfig() {
     if (!this._sortParams) return undefined;
     if (this._sortMethod === 'sort' && this._sortParams.fields?.length > 0) {
@@ -159,17 +87,10 @@ export class Ranking {
       return { method: 'linear', params: this._sortParams.map((p) => ({ field: p.field, weight: p.weight })) };
     }
     if (this._sortMethod === 'mix' && Array.isArray(this._sortParams) && this._sortParams.length > 0) {
-      return {
-        method: 'mix',
-        params: this._sortParams.map((p) => ({ field: p.field, direction: p.direction, percentage: p.percentage })),
-      };
+      return { method: 'mix', params: this._sortParams.map((p) => ({ field: p.field, direction: p.direction, percentage: p.percentage })) };
     }
     return undefined;
   }
-
-  /**
-   * @private
-   */
   _buildDiversityConfig() {
     if (!this._diversityMethod) return undefined;
     if (this._diversityMethod === 'fields' && this._diversityParams?.fields?.length > 0) {
@@ -182,25 +103,12 @@ export class Ranking {
     }
     return undefined;
   }
-
-  /**
-   * @private
-   */
   _buildLimitsByFieldConfig() {
     if (!this._limitsByFieldEnabled || !this._limitRules.length) return undefined;
     const everyN = Number(this._everyN);
     if (!Number.isInteger(everyN) || everyN < 2) return undefined;
-    return {
-      every_n: everyN,
-      rules: this._limitRules.map((r) => ({ field: r.field, limit: Number(r.limit) || 0 })),
-    };
+    return { every_n: everyN, rules: this._limitRules.map((r) => ({ field: r.field, limit: Number(r.limit) || 0 })) };
   }
-
-  /**
-   * Set the sorting method. Applies to subsequent sortBy / weight / mix calls.
-   * @param {'sort' | 'linear' | 'mix'} x - Sorting method
-   * @returns {this}
-   */
   sortingMethod(x) {
     if (x !== 'sort' && x !== 'linear' && x !== 'mix') {
       throw new Error('Ranking.sortingMethod: must be "sort", "linear", or "mix"');
@@ -211,31 +119,15 @@ export class Ranking {
     if (x === 'mix') this._sortParams = [];
     return this;
   }
-
-  /**
-   * Set sort by field(s) and direction(s). Applies when sortingMethod is 'sort'.
-   * If sorting method was not set yet, it is set to 'sort' for convenience.
-   * @param {string} field - Primary sort field
-   * @param {'asc' | 'desc'} [direction='desc'] - Primary direction
-   * @param {string} [field2] - Optional second sort field
-   * @param {'asc' | 'desc'} [direction2='desc'] - Optional second direction
-   * @returns {this}
-   */
   sortBy(field, direction = 'desc', field2, direction2 = 'desc') {
     if (this._sortMethod === 'linear' || this._sortMethod === 'mix') {
       throw new Error('Ranking.sortBy: only applies when sortingMethod is "sort" (already set to something else)');
     }
     this._sortMethod = 'sort';
-    if (!this._sortParams || !this._sortParams.fields) {
-      this._sortParams = { fields: [], direction: [] };
-    }
+    if (!this._sortParams || !this._sortParams.fields) this._sortParams = { fields: [], direction: [] };
     const f = typeof field === 'string' && field.trim() ? field.trim() : null;
-    if (!f) {
-      throw new Error('Ranking.sortBy: field must be a non-empty string');
-    }
-    if (direction !== 'asc' && direction !== 'desc') {
-      throw new Error('Ranking.sortBy: direction must be "asc" or "desc"');
-    }
+    if (!f) throw new Error('Ranking.sortBy: field must be a non-empty string');
+    if (direction !== 'asc' && direction !== 'desc') throw new Error('Ranking.sortBy: direction must be "asc" or "desc"');
     this._sortParams = { fields: [f], direction: [direction] };
     if (typeof field2 === 'string' && field2.trim()) {
       this._sortParams.fields.push(field2.trim());
@@ -243,168 +135,74 @@ export class Ranking {
     }
     return this;
   }
-
-  /**
-   * Add a weighted field for linear combination. Applies when sortingMethod is 'linear'.
-   * @param {string} field - Field name
-   * @param {number} w - Weight
-   * @returns {this}
-   */
   weight(field, w) {
-    if (this._sortMethod !== 'linear') {
-      throw new Error('Ranking.weight: only applies when sortingMethod is "linear"');
-    }
+    if (this._sortMethod !== 'linear') throw new Error('Ranking.weight: only applies when sortingMethod is "linear"');
     const f = typeof field === 'string' && field.trim() ? field.trim() : null;
-    if (!f) {
-      throw new Error('Ranking.weight: field must be a non-empty string');
-    }
+    if (!f) throw new Error('Ranking.weight: field must be a non-empty string');
     if (!Array.isArray(this._sortParams)) this._sortParams = [];
     this._sortParams.push({ field: f, weight: Number(w) });
     return this;
   }
-
-  /**
-   * Add a mix row (field, direction, percentage). Applies when sortingMethod is 'mix'.
-   * If sorting method was not set yet, it is set to 'mix' for convenience.
-   * @param {string} field - Field name
-   * @param {'asc' | 'desc'} direction - Sort direction
-   * @param {number} percentage - Percentage weight (0–100)
-   * @returns {this}
-   */
   mix(field, direction, percentage) {
-    if (this._sortMethod === 'linear') {
-      throw new Error('Ranking.mix: only applies when sortingMethod is "mix" (already set to "linear")');
-    }
+    if (this._sortMethod === 'linear') throw new Error('Ranking.mix: only applies when sortingMethod is "mix" (already set to "linear")');
     this._sortMethod = 'mix';
     if (!Array.isArray(this._sortParams)) this._sortParams = [];
     const f = typeof field === 'string' && field.trim() ? field.trim() : null;
-    if (!f) {
-      throw new Error('Ranking.mix: field must be a non-empty string');
-    }
-    if (direction !== 'asc' && direction !== 'desc') {
-      throw new Error('Ranking.mix: direction must be "asc" or "desc"');
-    }
+    if (!f) throw new Error('Ranking.mix: field must be a non-empty string');
+    if (direction !== 'asc' && direction !== 'desc') throw new Error('Ranking.mix: direction must be "asc" or "desc"');
     this._sortParams.push({ field: f, direction, percentage: Number(percentage) || 0 });
     return this;
   }
-
-  /**
-   * Set the diversity method.
-   * @param {'fields' | 'semantic'} method - Diversity method
-   * @returns {this}
-   */
   diversity(method) {
-    if (method !== 'fields' && method !== 'semantic') {
-      throw new Error('Ranking.diversity: method must be "fields" or "semantic"');
-    }
+    if (method !== 'fields' && method !== 'semantic') throw new Error('Ranking.diversity: method must be "fields" or "semantic"');
     this._diversityMethod = method;
     if (method === 'fields') this._diversityParams = { fields: [] };
     if (method === 'semantic') this._diversityParams = { lambda: 0.5, horizon: 20 };
     return this;
   }
-
-  /**
-   * Add field(s) for diversity when diversityMethod is 'fields'. Pass array or single field name.
-   * @param {string[] | string} arrayOrItem - Field name(s)
-   * @returns {this}
-   */
   fields(arrayOrItem) {
-    if (this._diversityMethod !== 'fields') {
-      throw new Error('Ranking.fields: only applies when diversity(method) is "fields"');
-    }
-    if (!this._diversityParams || !Array.isArray(this._diversityParams.fields)) {
-      this._diversityParams = { fields: [] };
-    }
+    if (this._diversityMethod !== 'fields') throw new Error('Ranking.fields: only applies when diversity(method) is "fields"');
+    if (!this._diversityParams || !Array.isArray(this._diversityParams.fields)) this._diversityParams = { fields: [] };
     const add = (name) => {
       const s = typeof name === 'string' && name.trim() ? name.trim() : null;
       if (s && !this._diversityParams.fields.includes(s)) this._diversityParams.fields.push(s);
     };
-    if (Array.isArray(arrayOrItem)) {
-      arrayOrItem.forEach(add);
-    } else {
-      add(arrayOrItem);
-    }
+    if (Array.isArray(arrayOrItem)) arrayOrItem.forEach(add);
+    else add(arrayOrItem);
     return this;
   }
-
-  /**
-   * Set horizon for diversity method 'semantic'. Default 20.
-   * @param {number} n - Horizon value
-   * @returns {this}
-   */
   horizon(n) {
-    if (this._diversityMethod !== 'semantic') {
-      throw new Error('Ranking.horizon: only applies when diversity(method) is "semantic"');
-    }
+    if (this._diversityMethod !== 'semantic') throw new Error('Ranking.horizon: only applies when diversity(method) is "semantic"');
     if (!this._diversityParams) this._diversityParams = { lambda: 0.5, horizon: 20 };
     this._diversityParams.horizon = Number(n);
     return this;
   }
-
-  /**
-   * Set lambda for diversity method 'semantic'. Default 0.5.
-   * @param {number} value - Lambda value (0–1)
-   * @returns {this}
-   */
   lambda(value) {
-    if (this._diversityMethod !== 'semantic') {
-      throw new Error('Ranking.lambda: only applies when diversity(method) is "semantic"');
-    }
+    if (this._diversityMethod !== 'semantic') throw new Error('Ranking.lambda: only applies when diversity(method) is "semantic"');
     if (!this._diversityParams) this._diversityParams = { lambda: 0.5, horizon: 20 };
     this._diversityParams.lambda = Number(value);
     return this;
   }
-
-  /**
-   * Enable limits-by-field. Use every(n) and limit(field, max) to configure.
-   * @returns {this}
-   */
   limitByField() {
     this._limitsByFieldEnabled = true;
     return this;
   }
-
-  /**
-   * Set window size (every_n) for limits by field. Default 10.
-   * @param {number} n - Window size (e.g. every 10 items)
-   * @returns {this}
-   */
   every(n) {
     this._everyN = Number(n);
     return this;
   }
-
-  /**
-   * Add a limit rule: max occurrences of field value per window.
-   * @param {string} field - Field name
-   * @param {number} max - Maximum count per window
-   * @returns {this}
-   */
   limit(field, max) {
     const f = typeof field === 'string' && field.trim() ? field.trim() : null;
-    if (!f) {
-      throw new Error('Ranking.limit: field must be a non-empty string');
-    }
+    if (!f) throw new Error('Ranking.limit: field must be a non-empty string');
     const existing = this._limitRules.find((r) => r.field === f);
     if (existing) existing.limit = Number(max) || 0;
     else this._limitRules.push({ field: f, limit: Number(max) || 0 });
     return this;
   }
-
-  /**
-   * Set the candidates (hits) to rank. Each should have _id, and optionally _features, _scores, _source.
-   * @param {Array} candidates - Array of hit objects
-   * @returns {this}
-   */
   candidates(candidates) {
     this._candidates = candidates;
     return this;
   }
-
-  /**
-   * Execute the ranking request. Sets lastCall and lastResult on success; throws on error.
-   * @returns {Promise<object>} The result object (result.result.items with item_id and score)
-   */
   async execute() {
     if (!Array.isArray(this._candidates) || this._candidates.length === 0) {
       throw new Error('Ranking.execute: candidates must be set and non-empty (pass to constructor or call candidates([...]))');
@@ -423,10 +221,7 @@ export class Ranking {
     const startTime = performance.now();
     const response = await fetch(url, {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this._apiKey}`,
-      },
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` },
       body: JSON.stringify(payload),
     });
     const frontendTime = Math.round(performance.now() - startTime);
@@ -446,31 +241,17 @@ export class Ranking {
     result.took_frontend = frontendTime;
     this.lastCall = { endpoint, payload };
     this.lastResult = result;
-
     const res = result.result;
-    if (!res) {
-      throw new Error('Ranking.execute: response result is undefined');
-    }
-
+    if (!res) throw new Error('Ranking.execute: response result is undefined');
     const resultItems = res.items || [];
     this._log('Ranking result:');
     this._log(`  took_frontend_ms: ${result.took_frontend}`);
     this._log(`  items: ${resultItems.length}`);
     return res;
   }
-
-  /**
-   * Log a string.
-   * @param {string} string
-   */
   log(string) {
     this._log(string);
   }
-
-  /**
-   * Show results.
-   * @param {*} results
-   */
   show(results) {
     this._show(results);
   }

package/V1/scoring/Scoring.js

@@ -1,41 +1,9 @@
-/**
- * Scoring client for MBD Studio SDK.
- * Fluent API: methods return the instance for chaining.
- * Score or rerank items for a given user using a selected model.
- */
-
 export class Scoring {
-  /** @type {string} */
-  _url;
-
-  /** @type {string} */
-  _apiKey;
-
-  /** @type {string | null} */
   _userId = null;
-
-  /** @type {string[]} */
   _itemIds = [];
-
-  /** @type {string | null} */
   _modelEndpoint = null;
-
-  /** @type {{ endpoint: string, payload: object } | null} */
   lastCall = null;
-
-  /** @type {object | null} */
   lastResult = null;
-
-  /**
-   * @param {Object} options
-   * @param {string} options.url - Scoring service base URL
-   * @param {string} options.apiKey - API key for authentication
-   * @param {string} [options.userId] - User id for scoring context
-   * @param {string[]} [options.itemIds] - Item ids to score/rerank
-   * @param {string} [options.origin='sdk'] - origin sent in backend call payloads
-   * @param {function(string): void} [options.log] - Optional override for log()
-   * @param {function(*): void} [options.show] - Optional override for show()
-   */
   constructor(options) {
     if (!options || typeof options !== 'object') {
       throw new Error('Scoring: options object is required');
@@ -52,71 +20,32 @@ export class Scoring {
     this._origin = typeof origin === 'string' && origin.trim() ? origin.trim() : 'sdk';
     this._log = typeof log === 'function' ? log : console.log.bind(console);
     this._show = typeof show === 'function' ? show : console.log.bind(console);
-    if (userId != null && typeof userId === 'string' && userId.trim()) {
-      this._userId = userId.trim();
-    }
+    if (userId != null && typeof userId === 'string' && userId.trim()) this._userId = userId.trim();
     if (Array.isArray(itemIds) && itemIds.length > 0) {
       this._itemIds = itemIds.map((id) => (typeof id === 'string' ? id : String(id)));
     }
   }
-
-  /**
-   * Return the endpoint path for the current model (must be set via model(endpoint)).
-   * @returns {string}
-   */
   getEndpoint() {
     if (!this._modelEndpoint || !this._modelEndpoint.trim()) {
       throw new Error('Scoring.getEndpoint: model endpoint must be set (call model(endpoint) first)');
     }
     return this._modelEndpoint.startsWith('/') ? this._modelEndpoint : `/${this._modelEndpoint}`;
   }
-
-  /**
-   * Build the request payload (origin + user_id + item_ids).
-   * @returns {object}
-   */
   getPayload() {
-    return {
-      origin: this._origin,
-      user_id: this._userId,
-      item_ids: [...this._itemIds],
-    };
+    return { origin: this._origin, user_id: this._userId, item_ids: [...this._itemIds] };
   }
-
-  /**
-   * Set the model endpoint for scoring/reranking (required).
-   * @param {string} endpoint - Endpoint path (e.g. '/scoring/ranking_model/polymarket-rerank-v1')
-   * @returns {this}
-   */
   model(endpoint) {
     this._modelEndpoint = endpoint;
     return this;
   }
-
-  /**
-   * Set the user id for scoring context.
-   * @param {string} userId - User identifier
-   * @returns {this}
-   */
   userId(userId) {
     this._userId = userId;
     return this;
   }
-
-  /**
-   * Set the item ids to score/rerank.
-   * @param {string[]} itemIds - Array of item id strings
-   * @returns {this}
-   */
   itemIds(itemIds) {
     this._itemIds = itemIds;
     return this;
   }
-
-  /**
-   * Execute the scoring request. Sets lastCall and lastResult on success; throws on error.
-   * @returns {Promise<object>} The result object (e.g. result.result with personalizedRanking, etc.)
-   */
   async execute() {
     if (!this._modelEndpoint || !this._modelEndpoint.trim()) {
       throw new Error('Scoring.execute: model endpoint must be set (call model(endpoint) first)');
@@ -134,10 +63,7 @@ export class Scoring {
     const startTime = performance.now();
     const response = await fetch(url, {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this._apiKey}`,
-      },
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` },
       body: JSON.stringify(payload),
     });
     const frontendTime = Math.round(performance.now() - startTime);
@@ -157,30 +83,16 @@ export class Scoring {
     result.took_frontend = frontendTime;
     this.lastCall = { endpoint, payload };
     this.lastResult = result;
-
     const res = result.result;
-    if (res === undefined) {
-      throw new Error('Scoring.execute: result.result is undefined');
-    }
-
+    if (res === undefined) throw new Error('Scoring.execute: result.result is undefined');
     this._log('Scoring result:');
     this._log(`  took_frontend_ms: ${result.took_frontend}`);
     this._log(`  Array length: ${res.length}`);
     return res;
   }
-
-  /**
-   * Log a string.
-   * @param {string} string
-   */
   log(string) {
     this._log(string);
   }
-
-  /**
-   * Show results.
-   * @param {*} results
-   */
   show(results) {
     this._show(results);
   }