mbd-studio-sdk 2.1.1 → 2.2.0

package/StudioConfig.js

@@ -1,127 +1,40 @@
-/**
- * @typedef {Object} ServicesUrl
- * @property {string} searchService - URL of the search service
- * @property {string} storiesService - URL of the stories service
- * @property {string} featuresService - URL of the features service
- * @property {string} scoringService - URL of the scoring service
- * @property {string} rankingService - URL of the ranking service
- */
-
-/**
- * @typedef {Object} StudioConfigOptions
- * @property {string} apiKey - API key for authentication (required)
- * @property {string} [commonUrl] - Base URL used for all services when provided
- * @property {ServicesUrl} [servicesUrl] - Per-service URLs when commonUrl is not provided
- * @property {function(string): void} [log] - Optional log function, defaults to console.log
- * @property {function(*): void} [show] - Optional show function, defaults to console.log
- */
-
-/**
- * Configuration for MBD Studio SDK.
- * Use commonUrl for a single URL for all services, or servicesUrl for one URL per service.
- */
 export class StudioConfig {
-  /**
-   * @param {StudioConfigOptions} options - Configuration options
-   * @throws {Error} When parameters are invalid or missing required fields
-   */
   constructor(options) {
     if (!options || typeof options !== 'object') {
       throw new Error('StudioConfig: options object is required');
     }
     const { apiKey, commonUrl, servicesUrl, log, show } = options;
-
     if (typeof apiKey !== 'string' || !apiKey.trim()) {
       throw new Error('StudioConfig: apiKey is required and must be a non-empty string');
     }
-
-    const hasCommonUrl =
-      typeof commonUrl === 'string' && commonUrl.trim().length > 0;
-
+    const hasCommonUrl = typeof commonUrl === 'string' && commonUrl.trim().length > 0;
     if (hasCommonUrl) {
       const url = commonUrl.trim().replace(/\/$/, '');
-      this._searchService = url;
-      this._storiesService = url;
-      this._featuresService = url;
-      this._scoringService = url;
-      this._rankingService = url;
+      this.searchService = url;
+      this.storiesService = url;
+      this.featuresService = url;
+      this.scoringService = url;
+      this.rankingService = url;
     } else {
       if (!servicesUrl || typeof servicesUrl !== 'object') {
-        throw new Error(
-          'StudioConfig: when commonUrl is not provided, servicesUrl must be an object with searchService, storiesService, featuresService, scoringService, rankingService'
-        );
+        throw new Error('StudioConfig: when commonUrl is not provided, servicesUrl must be an object with searchService, storiesService, featuresService, scoringService, rankingService');
       }
-      const {
-        searchService,
-        storiesService,
-        featuresService,
-        scoringService,
-        rankingService,
-      } = servicesUrl;
-      const services = {
-        searchService,
-        storiesService,
-        featuresService,
-        scoringService,
-        rankingService,
-      };
+      const { searchService, storiesService, featuresService, scoringService, rankingService } = servicesUrl;
+      const services = { searchService, storiesService, featuresService, scoringService, rankingService };
       const missing = Object.entries(services)
         .filter(([, v]) => typeof v !== 'string' || !v.trim())
         .map(([k]) => k);
       if (missing.length > 0) {
-        throw new Error(
-          `StudioConfig: when using servicesUrl, all service URLs are required. Missing or invalid: ${missing.join(', ')}`
-        );
+        throw new Error(`StudioConfig: when using servicesUrl, all service URLs are required. Missing or invalid: ${missing.join(', ')}`);
       }
-      this._searchService = searchService.trim().replace(/\/$/, '');
-      this._storiesService = storiesService.trim().replace(/\/$/, '');
-      this._featuresService = featuresService.trim().replace(/\/$/, '');
-      this._scoringService = scoringService.trim().replace(/\/$/, '');
-      this._rankingService = rankingService.trim().replace(/\/$/, '');
+      this.searchService = searchService.trim().replace(/\/$/, '');
+      this.storiesService = storiesService.trim().replace(/\/$/, '');
+      this.featuresService = featuresService.trim().replace(/\/$/, '');
+      this.scoringService = scoringService.trim().replace(/\/$/, '');
+      this.rankingService = rankingService.trim().replace(/\/$/, '');
     }
-
-    this._apiKey = apiKey.trim();
-    this._log = typeof log === 'function' ? log : console.log.bind(console);
-    this._show = typeof show === 'function' ? show : console.log.bind(console);
-  }
-
-  /** @returns {function(string): void} */
-  get log() {
-    return this._log;
-  }
-
-  /** @returns {function(*): void} */
-  get show() {
-    return this._show;
-  }
-
-  /** @returns {string} */
-  get searchService() {
-    return this._searchService;
-  }
-
-  /** @returns {string} */
-  get storiesService() {
-    return this._storiesService;
-  }
-
-  /** @returns {string} */
-  get featuresService() {
-    return this._featuresService;
-  }
-
-  /** @returns {string} */
-  get scoringService() {
-    return this._scoringService;
-  }
-
-  /** @returns {string} */
-  get rankingService() {
-    return this._rankingService;
-  }
-
-  /** @returns {string} */
-  get apiKey() {
-    return this._apiKey;
+    this.apiKey = apiKey.trim();
+    this.log = typeof log === 'function' ? log : console.log.bind(console);
+    this.show = typeof show === 'function' ? show : console.log.bind(console);
   }
 }

package/V1/Studio.js

@@ -1,8 +1,3 @@
-/**
- * Root entry point for the MBD Studio SDK.
- * Holds configuration and provides factory methods for service clients.
- */
-
 import { StudioConfig } from '../StudioConfig.js';
 import { Search } from './search/Search.js';
 import { Features, sortAvailableFeatures } from './features/Features.js';
@@ -10,62 +5,25 @@ import { Scoring } from './scoring/Scoring.js';
 import { Ranking } from './ranking/Ranking.js';
 import { findIndex } from './utils/indexUtils.js';
 
-/**
- * @typedef {Object} StudioOptions
- * @property {StudioConfig} [config] - Shared config instance (preferred). When provided, apiKey/commonUrl/servicesUrl are ignored.
- * @property {string} [apiKey] - API key for authentication (required when config is not provided)
- * @property {string} [commonUrl] - Base URL used for all services when provided
- * @property {{ searchService: string, storiesService: string, featuresService: string, scoringService: string, rankingService: string }} [servicesUrl] - Per-service URLs when commonUrl is not provided
- * @property {function(string): void} [log] - log function, defaults to console.log
- * @property {function(*): void} [show] - show function, defaults to console.log
- * @property {string} [origin='sdk'] - origin sent in backend call payloads
- */
-
-/**
- * Studio SDK client. Initialize with options; use search() to get a Search instance.
- * Pass a StudioConfig instance (config) for version-agnostic initialization, or apiKey/commonUrl/servicesUrl for legacy.
- */
 export class Studio {
-  /**
-   * @param {StudioOptions} options - Configuration options (config or apiKey+commonUrl/servicesUrl)
-   */
   constructor(options) {
     if (!options || typeof options !== 'object') {
       throw new Error('Studio: options object is required');
     }
     const { config, apiKey, commonUrl, servicesUrl, log, show, origin } = options;
-    this._config =
-      config instanceof StudioConfig
-        ? config
-        : new StudioConfig({ commonUrl, servicesUrl, apiKey });
-    this._log =
-      typeof log === 'function' ? log : this._config.log;
-    this._show =
-      typeof show === 'function' ? show : this._config.show;
+    this._config = config instanceof StudioConfig ? config : new StudioConfig({ commonUrl, servicesUrl, apiKey });
+    this._log = typeof log === 'function' ? log : this._config.log;
+    this._show = typeof show === 'function' ? show : this._config.show;
     this._origin = typeof origin === 'string' && origin.trim() ? origin.trim() : 'sdk';
     this._forUser = null;
     this._candidates = [];
   }
-
-  /* Return the SDK version */
   version() {
     return 'V1';
   }
-
-  /**
-   * Set the user for context (e.g. features). Puts { index, id } in this.forUser.
-   * (Stored internally as this._forUser; read studio._forUser or call studio.forUser() to set.)
-   * @param {number} index - User index
-   * @param {string} userId - User id
-   */
   forUser(index, userId) {
     this._forUser = { index, id: userId };
   }
-
-  /**
-   * Return a new Search instance configured with the studio's search service URL, API key, and origin.
-   * @returns {Search}
-   */
   search() {
     return new Search({
       url: this._config.searchService,
@@ -75,22 +33,11 @@ export class Studio {
       show: this._show,
     });
   }
-
-  /**
-   * Extend the candidates array with the given items.
-   * @param {Array} array - Items to add to candidates
-   */
   addCandidates(array) {
     this._candidates.push(...array);
   }
-
-  /**
-   * Return a new Features instance configured with the studio's features service URL and API key.
-   * If candidates are set, they are passed to the constructor as items by default
-   * @returns {Features}
-   */
-  features(version='v1') {
-    let items = []
+  features(version = 'v1') {
+    let items = [];
     if (this._candidates && this._candidates.length > 0) {
       items = this._candidates.map((hit) => ({ index: hit._index, id: hit._id }));
     }
@@ -106,18 +53,13 @@ export class Studio {
       origin: this._origin,
     });
   }
-
-  /**
-   * Merge feature service response into candidates (hits). Mutates each candidate with _features and _scores.
-   * @param {Object} featureServiceResponse 
-   */
   addFeatures(featuresResult) {
     const hits = this._candidates || [];
     const features = featuresResult.features;
     const scores = featuresResult.scores;
     if (!features && !scores) {
       this._log('No features or scores found in featuresResult');
-      return ;
+      return;
     }
     let availableFeatures = {};
     let availableScores = {};
@@ -132,9 +74,7 @@ export class Studio {
       }
       if (hit._features) {
         for (const [key, value] of Object.entries(hit._features)) {
-          if (typeof value === 'number' && !Number.isNaN(value)) {
-            availableFeatures[key] = true;
-          }
+          if (typeof value === 'number' && !Number.isNaN(value)) availableFeatures[key] = true;
         }
       }
       if (hit._scores) {
@@ -144,9 +84,7 @@ export class Studio {
       }
       if (hit._scores) {
         for (const [key, value] of Object.entries(hit._scores)) {
-          if (typeof value === 'number' && !Number.isNaN(value)) {
-            availableScores[key] = true;
-          }
+          if (typeof value === 'number' && !Number.isNaN(value)) availableScores[key] = true;
         }
       }
     }
@@ -155,19 +93,11 @@ export class Studio {
     this._log(`Available features: ${availableFeatures}`);
     this._log(`Available scores: ${availableScores}`);
   }
-
-
-  /**
-   * Return a new Scoring instance configured with the studio's scoring service URL and API key.
-   * If forUser is set, userId is passed; if candidates are set, item ids are extracted and passed.
-   * @returns {Scoring}
-   */
   scoring() {
     const userId = this._forUser?.id ?? null;
-    const itemIds =
-      Array.isArray(this._candidates) && this._candidates.length > 0
-        ? this._candidates.map((c) => (c && (c._id != null) ? String(c._id) : null)).filter(Boolean)
-        : [];
+    const itemIds = Array.isArray(this._candidates) && this._candidates.length > 0
+      ? this._candidates.map((c) => (c && (c._id != null) ? String(c._id) : null)).filter(Boolean)
+      : [];
     return new Scoring({
       url: this._config.scoringService,
       apiKey: this._config.apiKey,
@@ -178,39 +108,22 @@ export class Studio {
       origin: this._origin,
     });
   }
-
-  /**
-   * Add scores to candidates from a scoring/rerank result (ranking order).
-   * @param {string} endpoint - Model endpoint used (key for hit._scores)
-   * @param {Array} scoringResult - Array of item ids in ranking order
-   */
   addScores(scoringResult, scoringKey) {
     const rankedItemIds = scoringResult;
-    if (!this._candidates || !rankedItemIds || !Array.isArray(rankedItemIds)) {
-      return;
-    }
+    if (!this._candidates || !rankedItemIds || !Array.isArray(rankedItemIds)) return;
     const rankToScore = {};
     rankedItemIds.forEach((itemId, index) => {
-      const score = 1.0 - (index / rankedItemIds.length);
-      rankToScore[itemId] = score;
+      rankToScore[itemId] = 1.0 - (index / rankedItemIds.length);
     });
     for (const hit of this._candidates) {
       const hitId = hit._id;
       const hitScore = rankToScore[hitId];
       if (hitScore) {
-        if (!hit._scores) {
-          hit._scores = {};
-        }
+        if (!hit._scores) hit._scores = {};
         hit._scores[scoringKey] = rankToScore[hitId];
       }
     }
   }
-
-  /**
-   * Return a new Ranking instance configured with the studio's ranking service URL and API key.
-   * If candidates are set, they are passed to the constructor.
-   * @returns {Ranking}
-   */
   ranking() {
     return new Ranking({
       url: this._config.rankingService,
@@ -221,42 +134,20 @@ export class Studio {
       origin: this._origin,
     });
   }
-
-  /**
-   * Merge ranking result scores into candidates (hits). Mutates each candidate with _ranking_score.
-   * @param {Object} rankingResult - Result from Ranking.execute() (result.result with items array of { item_id, score })
-   */
   addRanking(rankingResult) {
     const rankedItems = rankingResult?.items;
-    if (!this._candidates || !rankedItems || !Array.isArray(rankedItems)) {
-      return;
-    }
+    if (!this._candidates || !rankedItems || !Array.isArray(rankedItems)) return;
     const scoreByItemId = {};
-    rankedItems.forEach(({ item_id, score }) => {
-      scoreByItemId[item_id] = score;
-    });
+    rankedItems.forEach(({ item_id, score }) => { scoreByItemId[item_id] = score; });
     for (const hit of this._candidates) {
       hit._ranking_score = scoreByItemId[hit._id];
     }
   }
-
-  /**
-   * Log a string. Uses custom implementation if provided to constructor, otherwise console.log.
-   * @param {string} string
-   */
   log(string) {
     this._log(string);
   }
-
-  /**
-   * Show results. Uses custom implementation if provided to constructor, otherwise console.log.
-   * @param {*} results
-   */
   show(results) {
-    if (results === undefined) {
-      results = this._candidates;
-    }
+    if (results === undefined) results = this._candidates;
     this._show(results);
   }
-
 }

package/V1/features/Features.js

@@ -1,36 +1,11 @@
-/**
- * Features client for MBD Studio SDK.
- * Fluent API: methods return the instance for chaining.
- * Enrich items with ML features (embeddings, affinity, etc.) for a given user.
- */
-
-/**
- * @typedef {{ index: string, id: string }} UserRef
- * @typedef {{ index: string, id: string }} ItemRef
- */
-
 export const PREFERRED_FEATURE_COLUMNS = [
-  'found',
-  'original_rank',
-  'sem_sim_fuzzy',
-  'sem_sim_closest',
-  'usr_primary_labels',
-  'usr_secondary_labels',
-  'usr_primary_tags',
-  'usr_secondary_tags',
-  'user_affinity_avg',
-  'user_affinity_usdc',
-  'user_affinity_count',
+  'found', 'original_rank', 'sem_sim_fuzzy', 'sem_sim_closest',
+  'usr_primary_labels', 'usr_secondary_labels', 'usr_primary_tags', 'usr_secondary_tags',
+  'user_affinity_avg', 'user_affinity_usdc', 'user_affinity_count',
   'cluster_1', 'cluster_2', 'cluster_3', 'cluster_4', 'cluster_5',
   'cluster_6', 'cluster_7', 'cluster_8', 'cluster_9', 'cluster_10',
   'sem_sim_cluster1', 'sem_sim_cluster2', 'sem_sim_cluster3', 'sem_sim_cluster4', 'sem_sim_cluster5',
 ];
-
-/**
- * Sort feature column names: preferred first, then regular, AI:, TAG:.
- * @param {string[]} available - Array of feature column names
- * @returns {string[]}
- */
 export function sortAvailableFeatures(available) {
   const preferred = PREFERRED_FEATURE_COLUMNS.filter((col) => available.includes(col));
   const nonPreferred = available.filter((col) => !PREFERRED_FEATURE_COLUMNS.includes(col));
@@ -39,41 +14,12 @@ export function sortAvailableFeatures(available) {
   const tagColumns = nonPreferred.filter((col) => col.startsWith('TAG:')).sort();
   return [...preferred, ...regular, ...aiColumns, ...tagColumns];
 }
-
 export class Features {
-  /** @type {string} */
-  _url;
-
-  /** @type {string} */
-  _apiKey;
-
-  /** @type {string} */
   _version = 'v1';
-
-  /** @type {UserRef | null} */
   _user = null;
-
-  /** @type {ItemRef[]} */
   _items = [];
-
-  /** @type {{ endpoint: string, payload: object } | null} */
   lastCall = null;
-
-  /** @type {object | null} */
   lastResult = null;
-
-  /**
-   * @param {Object} options
-   * @param {string} options.url - Features service base URL
-   * @param {string} options.apiKey - API key for authentication
-   * @param {string} [options.version='v1'] - API version
-   * @param {{ index: string, id: string }[]} [options.items] - Items to enrich
-   * @param {string} [options.userIndex] - User index for feature context
-   * @param {string} [options.userId] - User id for feature context
-   * @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('Features: options object is required');
@@ -91,69 +37,27 @@ export class Features {
     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 (Array.isArray(items) && items.length > 0) {
-      this._items = items;
-    }
-    if (userIndex != null && userId != null) {
-      this._user = { index: userIndex, id: userId };
-    }
+    if (Array.isArray(items) && items.length > 0) this._items = items;
+    if (userIndex != null && userId != null) this._user = { index: userIndex, id: userId };
   }
-
-  /**
-   * Return the endpoint path for the current version.
-   * @returns {string}
-   */
   getEndpoint() {
     return `/features/${this._version}`;
   }
-
-  /**
-   * Build the request payload (origin + user + items).
-   * @returns {object}
-   */
   getPayload() {
-    return {
-      origin: this._origin,
-      user: this._user,
-      items: this._items.map((item) => ({ ...item })),
-    };
+    return { origin: this._origin, user: this._user, items: this._items.map((item) => ({ ...item })) };
   }
-
-  /**
-   * Set the API version (e.g. 'v1'). Default is 'v1'.
-   * @param {string} v - Version string
-   * @returns {this}
-   */
   version(v) {
     this._version = v;
     return this;
   }
-
-  /**
-   * Set the items to enrich (array of { index, id }).
-   * @param {ItemRef[]} items - Array of { index: string, id: string }
-   * @returns {this}
-   */
   items(items) {
     this._items = [...items];
     return this;
   }
-
-  /**
-   * Set the user for feature computation (index + userId).
-   * @param {string} index - User index/table (e.g. 'polymarket-wallets')
-   * @param {string} userId - User identifier
-   * @returns {this}
-   */
   user(index, userId) {
     this._user = { index, id: userId };
     return this;
   }
-
-  /**
-   * Execute the features request. Sets lastCall and lastResult on success; throws on error.
-   * @returns {Promise<object>} The result object (result.items, result.user, result.feature_names, etc.)
-   */
   async execute() {
     if (!this._user || !this._user.index || !this._user.id) {
       throw new Error('Features.execute: user must be set (call user(index, userId) first)');
@@ -168,10 +72,7 @@ export class Features {
     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);
@@ -191,13 +92,8 @@ export class Features {
     result.took_frontend = frontendTime;
     this.lastCall = { endpoint, payload };
     this.lastResult = result;
-
     const res = result.result;
-    if (!res) {
-      throw new Error('Features.execute: result.result is undefined');
-    }
-
-    // Log infos (aligned with FeaturesInfoColumn.js)
+    if (!res) throw new Error('Features.execute: result.result is undefined');
     const infos = {
       took_frontend_ms: result.took_frontend,
       took_backend_ms: res.took_backend ?? 0,
@@ -227,22 +123,11 @@ export class Features {
     this._log(`  took_clustering_ms: ${infos.took_clustering_ms}`);
     this._log(`  hit_rate: ${infos.hit_rate_pct}%`);
     this._log(`  item_embed_rate: ${infos.item_embed_rate_pct}%`);
-
     return res;
   }
-
-  /**
-   * Log a string.
-   * @param {string} string
-   */
   log(string) {
     this._log(string);
   }
-
-  /**
-   * Show results.
-   * @param {*} results
-   */
   show(results) {
     this._show(results);
   }