mbd-studio-sdk 2.0.3

package/V1/Studio.js

@@ -0,0 +1,262 @@
+/**
+ * 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';
+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._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,
+      apiKey: this._config.apiKey,
+      origin: this._origin,
+      log: this._log,
+      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 = []
+    if (this._candidates && this._candidates.length > 0) {
+      items = this._candidates.map((hit) => ({ index: hit._index, id: hit._id }));
+    }
+    return new Features({
+      url: this._config.featuresService,
+      apiKey: this._config.apiKey,
+      log: this._log,
+      show: this._show,
+      version,
+      items,
+      userIndex: this._forUser?.index,
+      userId: this._forUser?.id,
+      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 ;
+    }
+    let availableFeatures = {};
+    let availableScores = {};
+    for (const hit of hits) {
+      const hitIndex = findIndex(hit._index);
+      const hitFeatures = features?.[hitIndex]?.[hit._id];
+      const hitScores = scores?.[hitIndex]?.[hit._id];
+      if (hit._features) {
+        hit._features = { ...hit._features, ...hitFeatures };
+      } else {
+        hit._features = hitFeatures;
+      }
+      if (hit._features) {
+        for (const [key, value] of Object.entries(hit._features)) {
+          if (typeof value === 'number' && !Number.isNaN(value)) {
+            availableFeatures[key] = true;
+          }
+        }
+      }
+      if (hit._scores) {
+        hit._scores = { ...hit._scores, ...hitScores };
+      } else {
+        hit._scores = hitScores;
+      }
+      if (hit._scores) {
+        for (const [key, value] of Object.entries(hit._scores)) {
+          if (typeof value === 'number' && !Number.isNaN(value)) {
+            availableScores[key] = true;
+          }
+        }
+      }
+    }
+    availableFeatures = sortAvailableFeatures(Object.keys(availableFeatures));
+    availableScores = sortAvailableFeatures(Object.keys(availableScores));
+    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)
+        : [];
+    return new Scoring({
+      url: this._config.scoringService,
+      apiKey: this._config.apiKey,
+      log: this._log,
+      show: this._show,
+      userId,
+      itemIds,
+      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;
+    }
+    const rankToScore = {};
+    rankedItemIds.forEach((itemId, index) => {
+      const score = 1.0 - (index / rankedItemIds.length);
+      rankToScore[itemId] = score;
+    });
+    for (const hit of this._candidates) {
+      const hitId = hit._id;
+      const hitScore = rankToScore[hitId];
+      if (hitScore) {
+        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,
+      apiKey: this._config.apiKey,
+      log: this._log,
+      show: this._show,
+      candidates: this._candidates,
+      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;
+    }
+    const scoreByItemId = {};
+    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;
+    }
+    this._show(results);
+  }
+
+}

package/V1/features/Features.js

@@ -0,0 +1,249 @@
+/**
+ * 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',
+  '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));
+  const regular = nonPreferred.filter((col) => !col.startsWith('AI:') && !col.startsWith('TAG:')).sort();
+  const aiColumns = nonPreferred.filter((col) => col.startsWith('AI:')).sort();
+  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');
+    }
+    const { url, apiKey, version = 'v1', items = [], userIndex, userId, origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) {
+      throw new Error('Features: options.url is required and must be a non-empty string');
+    }
+    if (typeof apiKey !== 'string' || !apiKey.trim()) {
+      throw new Error('Features: options.apiKey is required and must be a non-empty string');
+    }
+    this._url = url.trim().replace(/\/$/, '');
+    this._apiKey = apiKey.trim();
+    this._version = version;
+    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 };
+    }
+  }
+
+  /**
+   * 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 })),
+    };
+  }
+
+  /**
+   * 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)');
+    }
+    if (!Array.isArray(this._items) || this._items.length === 0) {
+      throw new Error('Features.execute: items must be set and non-empty (call items([...]) first)');
+    }
+    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 = `Features 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('Features.execute: result.result is undefined');
+    }
+
+    // Log infos (aligned with FeaturesInfoColumn.js)
+    const infos = {
+      took_frontend_ms: result.took_frontend,
+      took_backend_ms: res.took_backend ?? 0,
+      took_dynamo_user_ms: res.took_dynamo_user ?? 0,
+      took_dynamo_items_ms: res.took_dynamo_items ?? 0,
+      took_dynamo_interactions_ms: res.took_dynamo_interactions ?? 0,
+      took_features_ms: res.took_features ?? 0,
+      took_semantic_ms: res.took_semantic ?? 0,
+      took_topics_ms: res.took_topics ?? 0,
+      took_topic_similarity_ms: res.took_topic_similarity ?? 0,
+      took_user_affinity_ms: res.took_user_affinity ?? 0,
+      took_clustering_ms: res.took_clustering ?? 0,
+      hit_rate_pct: ((res.hit_rate ?? 0) * 100).toFixed(1),
+      item_embed_rate_pct: ((res.item_embed_rate ?? 0) * 100).toFixed(1),
+    };
+    this._log('Features result:');
+    this._log(`  took_frontend_ms: ${infos.took_frontend_ms}`);
+    this._log(`  took_backend_ms: ${infos.took_backend_ms}`);
+    this._log(`  took_dynamo_user_ms: ${infos.took_dynamo_user_ms}`);
+    this._log(`  took_dynamo_items_ms: ${infos.took_dynamo_items_ms}`);
+    this._log(`  took_dynamo_interactions_ms: ${infos.took_dynamo_interactions_ms}`);
+    this._log(`  took_features_ms: ${infos.took_features_ms}`);
+    this._log(`  took_semantic_ms: ${infos.took_semantic_ms}`);
+    this._log(`  took_topics_ms: ${infos.took_topics_ms}`);
+    this._log(`  took_topic_similarity_ms: ${infos.took_topic_similarity_ms}`);
+    this._log(`  took_user_affinity_ms: ${infos.took_user_affinity_ms}`);
+    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);
+  }
+}

package/V1/index.js

@@ -0,0 +1 @@
+export { Studio } from './Studio.js';