mbd-studio-sdk 2.0.3

package/V1/ranking/Ranking.js

@@ -0,0 +1,477 @@
+/**
+ * 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');
+    }
+    const { url, apiKey, candidates = [], origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) {
+      throw new Error('Ranking: options.url is required and must be a non-empty string');
+    }
+    if (typeof apiKey !== 'string' || !apiKey.trim()) {
+      throw new Error('Ranking: options.apiKey is required and must be a non-empty string');
+    }
+    this._url = url.trim().replace(/\/$/, '');
+    this._apiKey = apiKey.trim();
+    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);
+    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));
+      }
+      if (this._sortMethod === 'linear' && Array.isArray(this._sortParams)) {
+        this._sortParams.forEach((p) => p.field && useful.add(p.field));
+      }
+      if (this._sortMethod === 'mix' && Array.isArray(this._sortParams)) {
+        this._sortParams.forEach((p) => p.field && useful.add(p.field));
+      }
+    }
+    if (this._diversityMethod === 'fields' && this._diversityParams?.fields) {
+      this._diversityParams.fields.forEach((f) => useful.add(f));
+    }
+    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) {
+        const v = hit._features?.[key] ?? hit._scores?.[key];
+        if (v !== undefined) item[key] = v;
+      }
+      if (needEmbedding) {
+        let embed = hit._source?.item_sem_embed2;
+        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) {
+      return { method: 'sort', params: { ...this._sortParams } };
+    }
+    if (this._sortMethod === 'linear' && Array.isArray(this._sortParams) && this._sortParams.length > 0) {
+      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 undefined;
+  }
+
+  /**
+   * @private
+   */
+  _buildDiversityConfig() {
+    if (!this._diversityMethod) return undefined;
+    if (this._diversityMethod === 'fields' && this._diversityParams?.fields?.length > 0) {
+      return { method: 'fields', params: { fields: [...this._diversityParams.fields] } };
+    }
+    if (this._diversityMethod === 'semantic') {
+      const lambda = this._diversityParams?.lambda ?? 0.5;
+      const horizon = this._diversityParams?.horizon ?? 20;
+      return { method: 'semantic', params: { lambda: Number(lambda), horizon: Number(horizon) } };
+    }
+    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 })),
+    };
+  }
+
+  /**
+   * 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"');
+    }
+    this._sortMethod = x;
+    if (x === 'sort') this._sortParams = { fields: [], direction: [] };
+    if (x === 'linear') this._sortParams = [];
+    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: [] };
+    }
+    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"');
+    }
+    this._sortParams = { fields: [f], direction: [direction] };
+    if (typeof field2 === 'string' && field2.trim()) {
+      this._sortParams.fields.push(field2.trim());
+      this._sortParams.direction.push(direction2 === 'asc' ? 'asc' : 'desc');
+    }
+    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"');
+    }
+    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 (!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")');
+    }
+    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"');
+    }
+    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"');
+    }
+    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: [] };
+    }
+    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);
+    }
+    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._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._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');
+    }
+    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([...]))');
+    }
+    const sortConfig = this._buildSortConfig();
+    if (!sortConfig) {
+      throw new Error('Ranking.execute: at least one sort configuration is required (e.g. sortingMethod("sort").sortBy("field", "desc"))');
+    }
+    const endpoint = this.getEndpoint();
+    const payload = this.getPayload();
+    const url = `${this._url}${endpoint}`;
+    this.log(`Sending request to ${url}`);
+    const { items, ...rest } = payload;
+    const logPayload = { ...rest, items_length: Array.isArray(items) ? items.length : 0 };
+    this.log(`Payload:\n${JSON.stringify(logPayload, null, 2)}`);
+    const startTime = performance.now();
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this._apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+    const frontendTime = Math.round(performance.now() - startTime);
+    if (!response.ok) {
+      const text = await response.text();
+      let message = `Ranking API error: ${response.status} ${response.statusText}`;
+      if (text) message += ` — ${text}`;
+      this.log(message);
+      throw new Error(message);
+    }
+    const result = await response.json();
+    if (result && typeof result.error !== 'undefined' && result.error !== null) {
+      const msg = typeof result.error === 'string' ? result.error : String(result.error);
+      this.log(msg);
+      throw new Error(msg);
+    }
+    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');
+    }
+
+    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

@@ -0,0 +1,187 @@
+/**
+ * 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');
+    }
+    const { url, apiKey, userId = null, itemIds = [], origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) {
+      throw new Error('Scoring: options.url is required and must be a non-empty string');
+    }
+    if (typeof apiKey !== 'string' || !apiKey.trim()) {
+      throw new Error('Scoring: options.apiKey is required and must be a non-empty string');
+    }
+    this._url = url.trim().replace(/\/$/, '');
+    this._apiKey = apiKey.trim();
+    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 (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],
+    };
+  }
+
+  /**
+   * 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)');
+    }
+    if (!this._userId || typeof this._userId !== 'string' || !this._userId.trim()) {
+      throw new Error('Scoring.execute: user_id must be set (pass to constructor or call userId(id))');
+    }
+    if (!Array.isArray(this._itemIds) || this._itemIds.length === 0) {
+      throw new Error('Scoring.execute: item_ids must be set and non-empty (pass to constructor or call itemIds([...]))');
+    }
+    const endpoint = this.getEndpoint();
+    const payload = this.getPayload();
+    const url = `${this._url}${endpoint}`;
+    this.log(`Sending request to ${url}`);
+    const startTime = performance.now();
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this._apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+    const frontendTime = Math.round(performance.now() - startTime);
+    if (!response.ok) {
+      const text = await response.text();
+      let message = `Scoring API error: ${response.status} ${response.statusText}`;
+      if (text) message += ` — ${text}`;
+      this.log(message);
+      throw new Error(message);
+    }
+    const result = await response.json();
+    if (result && typeof result.error !== 'undefined' && result.error !== null) {
+      const msg = typeof result.error === 'string' ? result.error : String(result.error);
+      this.log(msg);
+      throw new Error(msg);
+    }
+    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');
+    }
+
+    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);
+  }
+}