mbd-studio-sdk 4.0.0 → 4.1.1

package/StudioConfig.js

@@ -1,6 +1,6 @@
 const defaultBaseUrl = 'https://api.mbd.xyz/v3/studio';
 
-
+/** API config: apiKey required; commonUrl (single base) or servicesUrl (per-service) for endpoints. */
 export class StudioConfig {
   constructor(options) {
     if (!options || typeof options !== 'object') {

package/V1/Studio.js

@@ -5,6 +5,7 @@ import { Scoring } from './scoring/Scoring.js';
 import { Ranking } from './ranking/Ranking.js';
 import { findIndex } from './utils/indexUtils.js';
 
+/** Main client: search, features, scoring, ranking. Use addCandidates() then addFeatures/addScores/addRanking to enrich. */
 export class Studio {
   constructor(options) {
     if (!options || typeof options !== 'object') {
@@ -56,6 +57,7 @@ export class Studio {
       origin: this._origin,
     });
   }
+  /** Merges featuresResult (features, scores, info) into hits. Keys use canonical index names (findIndex). */
   addFeatures(featuresResult) {
     const hits = this._candidates || [];
     const features = featuresResult.features;
@@ -118,6 +120,7 @@ export class Studio {
       origin: this._origin,
     });
   }
+  /** Maps ranked item IDs to scores (1.0 for rank 0, decreasing by rank). Merges into hit._scores[scoringKey]. */
   addScores(scoringResult, scoringKey) {
     const rankedItemIds = scoringResult;
     if (!this._candidates || !rankedItemIds || !Array.isArray(rankedItemIds)) return;
@@ -144,6 +147,7 @@ export class Studio {
       origin: this._origin,
     });
   }
+  /** Sets hit._ranking_score from ranking items, then sorts candidates by score descending. */
   addRanking(rankingResult) {
     const rankedItems = rankingResult?.items;
     if (!this._candidates || !rankedItems || !Array.isArray(rankedItems)) return;

package/V1/features/Features.js

@@ -1,3 +1,4 @@
+/** Feature columns shown first when listing available features (relevance, affinity, clusters, semantic). */
 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',
@@ -110,7 +111,7 @@ export class Features {
       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_sdk_ms: ${infos.took_sdk_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}`);

package/V1/ranking/Ranking.js

@@ -30,6 +30,7 @@ export class Ranking {
   getEndpoint() {
     return '/ranking/feed';
   }
+  /** Collects fields referenced by sort/diversity/limits; sets needEmbedding for semantic diversity. */
   _getUsefulFieldsAndNeedEmbedding() {
     const useful = new Set();
     let needEmbedding = false;
@@ -53,6 +54,7 @@ export class Ranking {
     }
     return { usefulFields: useful, needEmbedding };
   }
+  /** Builds items from hit._features, hit._scores; adds embed (item_sem_embed2 or text_vector) if semantic diversity. */
   getPayload() {
     const { usefulFields, needEmbedding } = this._getUsefulFieldsAndNeedEmbedding();
     const hits = this._candidates || [];

package/V1/search/Search.js

@@ -3,6 +3,7 @@ import {
   IsNullFilter, NotNullFilter, CustomFilter, GroupBoostFilter, TermsLookupFilter, ConsoleAccountFilter,
 } from './filters/index.js';
 
+/** Search builder: index(), include()/exclude()/boost(), filters, execute(). Call include/exclude/boost before adding filters. */
 export class Search {
   _index = null;
   _es_query = null;
@@ -16,6 +17,7 @@ export class Search {
   _include = [];
   _exclude = [];
   _boost = [];
+  /** Set by include()/exclude()/boost(); filters are pushed to whichever array is active. */
   _active_array = null;
   lastCall = null;
   lastResult = null;
@@ -36,6 +38,7 @@ export class Search {
     this._log = typeof log === 'function' ? log : console.log.bind(console);
     this._show = typeof show === 'function' ? show : console.log.bind(console);
   }
+  /** Endpoint selection: es_query > semantic (text/vector) > boost > filter_and_sort. */
   getEndpoint() {
     if (this._es_query != null) return '/search/es_query';
     const hasTextOrVector = (typeof this._text === 'string' && this._text.length > 0) || (Array.isArray(this._vector) && this._vector.length > 0);
@@ -76,7 +79,40 @@ export class Search {
     if (this._es_query != null && (typeof this._es_query !== 'object' || Array.isArray(this._es_query))) {
       throw new Error('Search.execute: esQuery() must be called with a plain object (e.g. { query: {...}, sort: [...] })');
     }
+    const hasOnlyIds = this._only_ids === true;
+    const hasSelectFields = Array.isArray(this._select_fields) && this._select_fields.length > 0;
+    const hasIncludeVector = this._include_vector === true;
+    const exclusiveCount = (hasOnlyIds ? 1 : 0) + (hasSelectFields ? 1 : 0) + (hasIncludeVector ? 1 : 0);
+    if (exclusiveCount > 1) {
+      throw new Error(
+        'Search: onlyIds, selectFields, and includeVectors are mutually exclusive; only one may be set at a time.'
+      );
+    }
     const endpoint = this.getEndpoint();
+    if (endpoint === '/search/es_query') {
+      if (this._include.length > 0 || this._exclude.length > 0 || this._boost.length > 0) {
+        throw new Error(
+          'Search: esQuery() does not support include(), exclude(), or boost() filters. Add filters directly in your Elasticsearch query.'
+        );
+      }
+    } else if (endpoint === '/search/semantic') {
+      if (this._include.length > 0 || this._exclude.length > 0 || this._boost.length > 0) {
+        throw new Error(
+          'Search: semantic search does not support include(), exclude(), or boost() filters. Use filter_and_sort or boost endpoints for filtering.'
+        );
+      }
+      if (this._sort_by != null) {
+        throw new Error(
+          'Search: semantic search does not support sortBy(). Results are ranked by similarity.'
+        );
+      }
+    } else if (endpoint === '/search/boost') {
+      if (this._sort_by != null) {
+        throw new Error(
+          'Search: boost endpoint does not support sortBy(). Use filter_and_sort for sorting.'
+        );
+      }
+    }
     const payload = this.getPayload();
     const url = `${this._url}${endpoint}`;
     this.log(`Sending request to ${url}`);

package/V1/search/filters/ConsoleAccountFilter.js

@@ -1,4 +1,6 @@
 import { Filter } from './Filter.js';
+
+/** Filters by console account data. path: dot-notation field in the account doc. */
 export class ConsoleAccountFilter extends Filter {
   constructor(field, value, path, boost = null) {
     super('console_account', field, boost);

package/V1/search/filters/Filter.js

@@ -1,3 +1,18 @@
+/**
+ * Ensures the value is an array. Backend expects array for terms/match filters.
+ * - Arrays are returned as-is
+ * - Strings are converted: comma-separated strings are split; single values wrapped in array
+ */
+export function normalizeToArray(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string') {
+    return value.includes(',')
+      ? value.split(',').map((s) => s.trim()).filter(Boolean)
+      : [value];
+  }
+  return value != null ? [value] : [];
+}
+
 export class Filter {
   constructor(filterType, field, boost = null) {
     if (new.target === Filter) throw new Error('Filter is abstract and cannot be instantiated directly');

package/V1/search/filters/GroupBoostFilter.js

@@ -1,4 +1,6 @@
 import { Filter } from './Filter.js';
+
+/** Boosts items by group membership. lookup_index/field/value identify the group; min_boost/max_boost/n control boost range. */
 export class GroupBoostFilter extends Filter {
   constructor(lookup_index, field, value, group, min_boost = null, max_boost = null, n = null) {
     super('group_boost', field, null);

package/V1/search/filters/MatchFilter.js

@@ -1,7 +1,7 @@
-import { Filter } from './Filter.js';
+import { Filter, normalizeToArray } from './Filter.js';
 export class MatchFilter extends Filter {
   constructor(field, value, boost = null) {
     super('match', field, boost);
-    this.value = value;
+    this.value = normalizeToArray(value);
   }
 }

package/V1/search/filters/TermsFilter.js

@@ -1,7 +1,7 @@
-import { Filter } from './Filter.js';
+import { Filter, normalizeToArray } from './Filter.js';
 export class TermsFilter extends Filter {
   constructor(field, value, boost = null) {
     super('terms', field, boost);
-    this.value = value;
+    this.value = normalizeToArray(value);
   }
 }

package/V1/search/filters/TermsLookupFilter.js

@@ -1,4 +1,6 @@
 import { Filter } from './Filter.js';
+
+/** Filters by terms fetched from another index. path: dot-notation field in lookup doc (e.g. "followers.ids"). */
 export class TermsLookupFilter extends Filter {
   constructor(lookup_index, field, value, path, boost = null) {
     super('terms_lookup', field, boost);

package/V1/utils/indexUtils.js

@@ -1,3 +1,4 @@
+/** Maps index names to canonical base (e.g. farcaster-items-v2 → farcaster-items). Used for feature/score keys. */
 export function findIndex(index) {
   const indexOptions = ['farcaster-items', 'zora-coins', 'polymarket-items', 'polymarket-wallets'];
   for (const option of indexOptions) {

package/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * MBD Studio SDK – search, features, scoring, and ranking for personalized feeds.
+ * @example
+ * const config = new StudioConfig({ apiKey, commonUrl });
+ * const studio = new StudioV1({ config });
+ * const hits = await studio.search().index('farcaster-items').include().term('type', 'cast').execute();
+ */
+
+// --- StudioConfig ---
+
+export interface StudioConfigOptions {
+  apiKey: string;
+  commonUrl?: string;
+  servicesUrl?: {
+    searchService: string;
+    storiesService: string;
+    featuresService: string;
+    scoringService: string;
+    rankingService: string;
+  };
+  log?: (msg: string) => void;
+  show?: (results?: unknown) => void;
+}
+
+export class StudioConfig {
+  constructor(options: StudioConfigOptions);
+}
+
+// --- Filter (abstract base, used by Search.filter()) ---
+
+export class Filter {
+  constructor(filterType: string, field: string, boost?: number | null);
+}
+
+// --- Search ---
+
+export interface SearchHit {
+  _index?: string;
+  _id?: string;
+  _source?: Record<string, unknown>;
+  _features?: Record<string, number>;
+  _scores?: Record<string, number>;
+  _info?: Record<string, unknown>;
+  _ranking_score?: number;
+}
+
+export interface SearchResult {
+  total_hits?: number;
+  hits?: SearchHit[];
+  took_es?: number;
+  took_backend?: number;
+  max_score?: number;
+}
+
+export interface FrequentValuesResult {
+  [key: string]: unknown;
+}
+
+export class Search {
+  lastCall: { endpoint: string; payload: unknown } | null;
+  lastResult: unknown;
+
+  index(selected_index: string): this;
+  size(size: number): this;
+  onlyIds(value?: boolean): this;
+  includeVectors(value?: boolean): this;
+  selectFields(fields: string[] | null): this;
+  text(text: string): this;
+  vector(vector: number[]): this;
+  esQuery(rawQuery: Record<string, unknown>): this;
+  sortBy(field: string, direction?: 'asc' | 'desc', field2?: string, direction2?: 'asc' | 'desc'): this;
+  include(): this;
+  exclude(): this;
+  boost(): this;
+  filter(filterInstance: Filter): this;
+  term(field: string, value: string | number | boolean, boost?: number | null): this;
+  terms(field: string, values: (string | number | boolean)[], boost?: number | null): this;
+  numeric(field: string, operator: string, value: number, boost?: number | null): this;
+  date(field: string, dateFrom?: string | null, dateTo?: string | null, boost?: number | null): this;
+  geo(field: string, value: unknown, boost?: number | null): this;
+  match(field: string, value: string, boost?: number | null): this;
+  isNull(field: string, boost?: number | null): this;
+  notNull(field: string, boost?: number | null): this;
+  custom(field: string, value: unknown, boost?: number | null): this;
+  groupBoost(
+    lookup_index: string,
+    field: string,
+    value: unknown,
+    group: string,
+    min_boost?: number | null,
+    max_boost?: number | null,
+    n?: number | null
+  ): this;
+  termsLookup(
+    lookup_index: string,
+    field: string,
+    value: unknown,
+    path: string,
+    boost?: number | null
+  ): this;
+  consoleAccount(field: string, value: unknown, path: string, boost?: number | null): this;
+  execute(): Promise<SearchHit[]>;
+  frequentValues(field: string, size?: number): Promise<FrequentValuesResult>;
+  lookup(docId: string): Promise<unknown>;
+  log(string: string): void;
+  show(results?: unknown): void;
+}
+
+// --- Features ---
+
+export interface FeaturesResult {
+  features?: Record<string, Record<string, Record<string, number>>>;
+  scores?: Record<string, Record<string, Record<string, number>>>;
+  info?: Record<string, Record<string, Record<string, unknown>>>;
+  took_backend?: number;
+  hit_rate?: number;
+  item_embed_rate?: number;
+  [key: string]: unknown;
+}
+
+export class Features {
+  lastCall: { endpoint: string; payload: unknown } | null;
+  lastResult: unknown;
+
+  version(v: string): this;
+  items(items: Array<{ index: string; id: string }>): this;
+  user(index: string, userId: string): this;
+  execute(): Promise<FeaturesResult>;
+  log(string: string): void;
+  show(results?: unknown): void;
+}
+
+// --- Scoring ---
+
+export class Scoring {
+  lastCall: { endpoint: string; payload: unknown } | null;
+  lastResult: unknown;
+
+  model(endpoint: string): this;
+  userId(userId: string): this;
+  itemIds(itemIds: string[]): this;
+  execute(): Promise<string[]>;
+  log(string: string): void;
+  show(results?: unknown): void;
+}
+
+// --- Ranking ---
+
+export interface RankingItem {
+  item_id: string;
+  score: number;
+}
+
+export interface RankingResult {
+  items: RankingItem[];
+  [key: string]: unknown;
+}
+
+export class Ranking {
+  lastCall: { endpoint: string; payload: unknown } | null;
+  lastResult: unknown;
+
+  sortingMethod(x: 'sort' | 'linear' | 'mix'): this;
+  sortBy(
+    field: string,
+    direction?: 'asc' | 'desc',
+    field2?: string,
+    direction2?: 'asc' | 'desc'
+  ): this;
+  weight(field: string, w: number): this;
+  mix(field: string, direction: 'asc' | 'desc', percentage: number): this;
+  diversity(method: 'fields' | 'semantic'): this;
+  fields(arrayOrItem: string | string[]): this;
+  horizon(n: number): this;
+  lambda(value: number): this;
+  limitByField(): this;
+  every(n: number): this;
+  limit(field: string, max: number): this;
+  candidates(candidates: SearchHit[]): this;
+  execute(): Promise<RankingResult>;
+  log(string: string): void;
+  show(results?: unknown): void;
+}
+
+// --- Studio (main client) ---
+
+export interface StudioOptions {
+  config?: StudioConfig;
+  apiKey?: string;
+  commonUrl?: string;
+  servicesUrl?: StudioConfigOptions['servicesUrl'];
+  log?: (msg: string) => void;
+  show?: (results?: unknown) => void;
+  origin?: string;
+}
+
+export class Studio {
+  constructor(options: StudioOptions);
+
+  version(): string;
+  forUser(index: string, userId: string): void;
+  search(): Search;
+  frequentValues(index: string, field: string, size?: number): Promise<FrequentValuesResult>;
+  addCandidates(array: SearchHit[]): void;
+  features(version?: string): Features;
+  addFeatures(featuresResult: FeaturesResult): void;
+  scoring(): Scoring;
+  addScores(scoringResult: string[], scoringKey: string): void;
+  ranking(): Ranking;
+  addRanking(rankingResult: { items?: RankingItem[] }): void;
+  log(string: string): void;
+  show(results?: SearchHit[]): void;
+  getFeed(): SearchHit[];
+}
+
+// --- Main export ---
+
+export const StudioV1: typeof Studio;

package/index.js

@@ -1,3 +1,10 @@
+/**
+ * MBD Studio SDK – search, features, scoring, and ranking for personalized feeds.
+ * @example
+ * const config = new StudioConfig({ apiKey, commonUrl });
+ * const studio = new StudioV1({ config });
+ * const hits = await studio.search().index('farcaster-items').include().term('type', 'cast').execute();
+ */
 import * as V1 from './V1/index.js';
 export { StudioConfig } from './StudioConfig.js';
 export const StudioV1 = V1.Studio;

package/llms.txt

@@ -0,0 +1,581 @@
+# MBD Studio SDK – Reference for AI Coding Agents
+
+## Overview
+
+SDK for MBD Studio backend services: **search** (candidate retrieval), **features** (signals/metadata), **scoring** (ML models for relevance/reranking), and **ranking** (final ranked feed with diversity).
+
+## Entry Points
+
+- `StudioConfig` – API config (apiKey required; commonUrl or servicesUrl for endpoints)
+- `StudioV1` – Main client. Import: `import { StudioConfig, StudioV1 } from 'mbd-studio-sdk'`
+
+## Typical Flow
+
+1. `new StudioConfig({ apiKey })` → `new StudioV1({ config })`
+2. `mbd.forUser(index, userId)` – set user for personalization (optional)
+3. `mbd.search().index("...").include()/exclude()/boost().term(...).execute()` → hits
+4. `mbd.addCandidates(hits)` – attach hits to context
+5. `mbd.features("v1").execute()` → `mbd.addFeatures(result)` – enrich with signals
+6. `mbd.scoring().model("/scoring/...").execute()` → `mbd.addScores(result, "key")` – ML scores
+7. `mbd.ranking().sortingMethod(...).mix(...).execute()` → `mbd.addRanking(result)`
+8. `mbd.getFeed()` – final ranked candidates
+
+**Tip:** Search endpoints are chosen by payload: `es_query` > `semantic` (text/vector) > `boost` > `filter_and_sort`. Call `include()`/`exclude()`/`boost()` before adding filters. `findIndex()` maps index names (e.g. `farcaster-items-v2`) to canonical keys for feature/score lookups.
+
+---
+
+## index.js
+
+```javascript
+import * as V1 from './V1/index.js';
+export { StudioConfig } from './StudioConfig.js';
+export const StudioV1 = V1.Studio;
+```
+
+---
+
+## StudioConfig.js
+
+```javascript
+const defaultBaseUrl = 'https://api.mbd.xyz/v3/studio';
+export class StudioConfig {
+  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;
+    if (hasCommonUrl) {
+      const url = commonUrl.trim().replace(/\/$/, '');
+      this.searchService = this.storiesService = this.featuresService = this.scoringService = this.rankingService = url;
+    } else if (servicesUrl && typeof servicesUrl === 'object') {
+      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: ${missing.join(', ')}`);
+      [this.searchService, this.storiesService, this.featuresService, this.scoringService, this.rankingService] =
+        [searchService, storiesService, featuresService, scoringService, rankingService].map((u) => u.trim().replace(/\/$/, ''));
+    } else {
+      this.searchService = this.storiesService = this.featuresService = this.scoringService = this.rankingService = defaultBaseUrl;
+    }
+    this.apiKey = apiKey.trim();
+    this.log = typeof log === 'function' ? log : console.log.bind(console);
+    this.show = typeof show === 'function' ? show : console.log.bind(console);
+  }
+}
+```
+
+---
+
+## V1/index.js
+
+```javascript
+export { Studio } from './Studio.js';
+```
+
+---
+
+## V1/utils/indexUtils.js
+
+```javascript
+// Maps index names to canonical base (e.g. farcaster-items-v2 → farcaster-items). Used for feature/score keys.
+export function findIndex(index) {
+  const indexOptions = ['farcaster-items', 'zora-coins', 'polymarket-items', 'polymarket-wallets'];
+  for (const option of indexOptions) if (index.startsWith(option)) return option;
+  return null;
+}
+```
+
+---
+
+## V1/Studio.js
+
+```javascript
+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';
+
+export class Studio {
+  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 = [];
+  }
+  version() { return 'V1'; }
+  forUser(index, userId) { this._forUser = { index, id: userId }; }
+  search() { return new Search({ url: this._config.searchService, apiKey: this._config.apiKey, origin: this._origin, log: this._log, show: this._show }); }
+  async frequentValues(index, field, size = 25) { return this.search().index(index).frequentValues(field, size); }
+  addCandidates(array) { this._candidates.push(...array); }
+  features(version = 'v1') {
+    let items = [];
+    if (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 });
+  }
+  addFeatures(featuresResult) {
+    const hits = this._candidates || [];
+    const { features, scores, info } = featuresResult;
+    if (!features && !scores && !info) { this._log('No features, scores, or info found'); return; }
+    let availableFeatures = {}, availableScores = {};
+    for (const hit of hits) {
+      const hitIndex = findIndex(hit._index);
+      const hitFeatures = features?.[hitIndex]?.[hit._id], hitScores = scores?.[hitIndex]?.[hit._id], hitInfo = info?.[hitIndex]?.[hit._id];
+      hit._features = hit._features ? { ...hit._features, ...hitFeatures } : hitFeatures;
+      hit._scores = hit._scores ? { ...hit._scores, ...hitScores } : hitScores;
+      hit._info = hit._info ? { ...hit._info, ...hitInfo } : hitInfo;
+      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) for (const [key, value] of Object.entries(hit._scores)) if (typeof value === 'number' && !Number.isNaN(value)) availableScores[key] = true;
+    }
+    this._log(`Available features: ${sortAvailableFeatures(Object.keys(availableFeatures))}`);
+    this._log(`Available scores: ${sortAvailableFeatures(Object.keys(availableScores))}`);
+  }
+  scoring() {
+    const userId = this._forUser?.id ?? null;
+    const itemIds = Array.isArray(this._candidates) && this._candidates.length > 0 ? this._candidates.map((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 });
+  }
+  addScores(scoringResult, scoringKey) {
+    const rankedItemIds = scoringResult;
+    if (!this._candidates || !Array.isArray(rankedItemIds)) return;
+    const rankToScore = {}; rankedItemIds.forEach((itemId, i) => { rankToScore[itemId] = 1.0 - (i / rankedItemIds.length); });
+    for (const hit of this._candidates) if (rankToScore[hit._id] != null) { if (!hit._scores) hit._scores = {}; hit._scores[scoringKey] = rankToScore[hit._id]; }
+  }
+  ranking() { return new Ranking({ url: this._config.rankingService, apiKey: this._config.apiKey, log: this._log, show: this._show, candidates: this._candidates, origin: this._origin }); }
+  addRanking(rankingResult) {
+    const rankedItems = rankingResult?.items;
+    if (!this._candidates || !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];
+    this._candidates.sort((a, b) => (b._ranking_score ?? -Infinity) - (a._ranking_score ?? -Infinity));
+  }
+  log(string) { this._log(string); }
+  show(results) { this._show(results === undefined ? this._candidates : results); }
+  getFeed() { return this._candidates; }
+}
+```
+
+---
+
+## V1/search/Search.js
+
+```javascript
+import { Filter, TermFilter, TermsFilter, NumericFilter, MatchFilter, GeoFilter, DateFilter, IsNullFilter, NotNullFilter, CustomFilter, GroupBoostFilter, TermsLookupFilter, ConsoleAccountFilter } from './filters/index.js';
+
+export class Search {
+  _index = null; _es_query = null; _size = 100; _only_ids = false; _include_vector = false; _select_fields = null;
+  _text = null; _vector = null; _sort_by = null; _include = []; _exclude = []; _boost = [];
+  _active_array = null; lastCall = null; lastResult = null;
+  constructor(options) {
+    if (!options || typeof options !== 'object') throw new Error('Search: options object is required');
+    const { url, apiKey, origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) throw new Error('Search: options.url is required');
+    if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('Search: options.apiKey is required');
+    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);
+  }
+  getEndpoint() {
+    if (this._es_query != null) return '/search/es_query';
+    const hasTextOrVector = (typeof this._text === 'string' && this._text.length > 0) || (Array.isArray(this._vector) && this._vector.length > 0);
+    if (hasTextOrVector) return '/search/semantic';
+    if (this._boost.length > 0) return '/search/boost';
+    return '/search/filter_and_sort';
+  }
+  getPayload() {
+    const endpoint = this.getEndpoint();
+    if (endpoint === '/search/es_query') return { index: this._index, origin: this._origin, feed_type: 'es_query', query: this._es_query };
+    const feedType = endpoint === '/search/semantic' ? 'semantic' : endpoint === '/search/boost' ? 'boost' : 'filter_and_sort';
+    const serializeFilters = (arr) => arr.map((f) => ({ ...f }));
+    const payload = { index: this._index, origin: this._origin, feed_type: feedType, include_vector: this._include_vector, size: this._size, include: serializeFilters(this._include), exclude: serializeFilters(this._exclude) };
+    if (feedType === 'boost') payload.boost = serializeFilters(this._boost);
+    if (feedType === 'filter_and_sort' && this._sort_by) payload.sort_by = this._sort_by;
+    if (feedType === 'semantic') {
+      if (typeof this._text === 'string' && this._text.length > 0) payload.text = this._text;
+      if (Array.isArray(this._vector) && this._vector.length > 0) payload.vector = this._vector;
+    }
+    if (this._only_ids) payload.only_ids = true;
+    if (Array.isArray(this._select_fields) && this._select_fields.length > 0) payload.select_fields = this._select_fields;
+    return payload;
+  }
+  async execute() {
+    if (!this._index || typeof this._index !== 'string' || !this._index.trim()) throw new Error('Search.execute: index must be set');
+    if (this._es_query != null && (typeof this._es_query !== 'object' || Array.isArray(this._es_query))) throw new Error('Search.execute: esQuery() must be called with a plain object');
+    const hasOnlyIds = this._only_ids === true, hasSelectFields = Array.isArray(this._select_fields) && this._select_fields.length > 0, hasIncludeVector = this._include_vector === true;
+    if ((hasOnlyIds ? 1 : 0) + (hasSelectFields ? 1 : 0) + (hasIncludeVector ? 1 : 0) > 1) throw new Error('Search: onlyIds, selectFields, includeVectors are mutually exclusive');
+    const endpoint = this.getEndpoint();
+    if (endpoint === '/search/es_query' && (this._include.length || this._exclude.length || this._boost.length)) throw new Error('Search: esQuery() does not support include/exclude/boost');
+    if (endpoint === '/search/semantic') {
+      if (this._include.length || this._exclude.length || this._boost.length) throw new Error('Search: semantic does not support include/exclude/boost');
+      if (this._sort_by != null) throw new Error('Search: semantic does not support sortBy()');
+    }
+    if (endpoint === '/search/boost' && this._sort_by != null) throw new Error('Search: boost does not support sortBy()');
+    const payload = this.getPayload(), 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) });
+    if (!response.ok) { const text = await response.text(); throw new Error(`Search API error: ${response.status} — ${text}`); }
+    const result = await response.json();
+    if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error));
+    result.took_sdk = Math.round(performance.now() - startTime);
+    this.lastCall = { endpoint, payload }; this.lastResult = result;
+    if (!result.result) throw new Error('Search.execute: result.result is undefined');
+    const res = result.result; return res.hits;
+  }
+  async frequentValues(field, size = 25) {
+    if (!this._index || typeof this._index !== 'string' || !this._index.trim()) throw new Error('Search.frequentValues: index must be set');
+    if (typeof field !== 'string' || !field.trim()) throw new Error('Search.frequentValues: field must be non-empty');
+    const n = Number(size); if (!Number.isInteger(n) || n <= 0) throw new Error('Search.frequentValues: size must be positive integer');
+    const endpoint = `/search/frequent_values/${encodeURIComponent(this._index)}/${encodeURIComponent(field.trim())}?size=${n}`;
+    const response = await fetch(`${this._url}${endpoint}`, { method: 'GET', headers: { Authorization: `Bearer ${this._apiKey}` } });
+    if (!response.ok) throw new Error(`frequentValues error: ${response.status}`);
+    const result = await response.json(); if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error)); return result;
+  }
+  async lookup(docId) {
+    if (!this._index || typeof this._index !== 'string' || !this._index.trim()) throw new Error('Search.lookup: index must be set');
+    if (typeof docId !== 'string' || !docId.trim()) throw new Error('Search.lookup: docId must be non-empty');
+    const endpoint = `/search/document/${encodeURIComponent(this._index)}/${encodeURIComponent(docId.trim())}`;
+    const response = await fetch(`${this._url}${endpoint}`, { method: 'GET', headers: { Authorization: `Bearer ${this._apiKey}` } });
+    if (!response.ok) throw new Error(`lookup error: ${response.status}`);
+    const result = await response.json(); if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error)); return result;
+  }
+  index(selected_index) { if (typeof selected_index !== 'string' || !selected_index.trim()) throw new Error('Search.index: selected_index required'); this._index = selected_index.trim(); return this; }
+  size(size) { const n = Number(size); if (!Number.isInteger(n) || n <= 0 || n >= 2000) throw new Error('Search.size: 0 < size < 2000'); this._size = n; return this; }
+  onlyIds(value) { this._only_ids = value == null ? true : Boolean(value); return this; }
+  includeVectors(value) { this._include_vector = value == null ? true : Boolean(value); return this; }
+  selectFields(fields) { if (fields === null) { this._select_fields = null; return this; } if (!Array.isArray(fields)) throw new Error('Search.selectFields: array or null'); this._select_fields = fields.map((f) => (typeof f === 'string' ? f.trim() : String(f))); return this; }
+  text(text) { if (typeof text !== 'string' || !text.trim()) throw new Error('Search.text: non-empty string'); this._text = text.trim(); return this; }
+  vector(vector) { if (!Array.isArray(vector)) throw new Error('Search.vector: array required'); this._vector = vector; return this; }
+  esQuery(rawQuery) { if (rawQuery == null || typeof rawQuery !== 'object' || Array.isArray(rawQuery)) throw new Error('Search.esQuery: plain object'); this._es_query = rawQuery; return this; }
+  sortBy(field, direction = 'desc') { if (typeof field !== 'string' || !field.trim()) throw new Error('Search.sortBy: field required'); if (direction !== 'asc' && direction !== 'desc') throw new Error('Search.sortBy: asc|desc'); this._sort_by = { field: field.trim(), order: direction }; return this; }
+  include() { this._active_array = this._include; return this; }
+  exclude() { this._active_array = this._exclude; return this; }
+  boost() { this._active_array = this._boost; return this; }
+  _requireActiveArray() { if (this._active_array === null) throw new Error('Search: call include(), exclude(), or boost() before filters'); }
+  _requireBoostForBoostArray(boost) { if (this._active_array === this._boost && boost == null) throw new Error('Search: boost array requires non-null boost'); }
+  filter(filterInstance) {
+    this._requireActiveArray();
+    if (filterInstance == null || !(filterInstance instanceof Filter)) throw new Error('Search.filter: Filter instance required');
+    if (this._active_array === this._boost && filterInstance.filter !== 'group_boost' && filterInstance.boost == null) throw new Error('Search: boost array requires non-null boost (group_boost exempt)');
+    this._active_array.push(filterInstance); return this;
+  }
+  term(field, value, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new TermFilter(field, value, boost)); return this; }
+  terms(field, values, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new TermsFilter(field, values, boost)); return this; }
+  numeric(field, operator, value, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new NumericFilter(field, operator, value, boost)); return this; }
+  date(field, dateFrom = null, dateTo = null, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new DateFilter(field, dateFrom, dateTo, boost)); return this; }
+  geo(field, value, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new GeoFilter(field, value, boost)); return this; }
+  match(field, value, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new MatchFilter(field, value, boost)); return this; }
+  isNull(field, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new IsNullFilter(field, boost)); return this; }
+  notNull(field, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new NotNullFilter(field, boost)); return this; }
+  custom(field, value, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new CustomFilter(field, value, boost)); return this; }
+  groupBoost(lookup_index, field, value, group, min_boost = null, max_boost = null, n = null) { this._requireActiveArray(); this._active_array.push(new GroupBoostFilter(lookup_index, field, value, group, min_boost, max_boost, n)); return this; }
+  termsLookup(lookup_index, field, value, path, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new TermsLookupFilter(lookup_index, field, value, path, boost)); return this; }
+  consoleAccount(field, value, path, boost = null) { this._requireActiveArray(); this._requireBoostForBoostArray(boost); this._active_array.push(new ConsoleAccountFilter(field, value, path, boost)); return this; }
+  log(string) { this._log(string); }
+  show(results) { this._show(results); }
+}
+```
+
+---
+
+## V1/search/filters/Filter.js
+
+```javascript
+export function normalizeToArray(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string') return value.includes(',') ? value.split(',').map((s) => s.trim()).filter(Boolean) : [value];
+  return value != null ? [value] : [];
+}
+export class Filter {
+  constructor(filterType, field, boost = null) {
+    if (new.target === Filter) throw new Error('Filter is abstract');
+    this.filter = filterType; this.field = field; this.boost = boost;
+  }
+}
+```
+
+---
+
+## V1/search/filters/index.js
+
+```javascript
+export { Filter } from './Filter.js';
+export { TermFilter } from './TermFilter.js';
+export { TermsFilter } from './TermsFilter.js';
+export { NumericFilter } from './NumericFilter.js';
+export { MatchFilter } from './MatchFilter.js';
+export { GeoFilter } from './GeoFilter.js';
+export { DateFilter } from './DateFilter.js';
+export { IsNullFilter } from './IsNullFilter.js';
+export { NotNullFilter } from './NotNullFilter.js';
+export { CustomFilter } from './CustomFilter.js';
+export { GroupBoostFilter } from './GroupBoostFilter.js';
+export { TermsLookupFilter } from './TermsLookupFilter.js';
+export { ConsoleAccountFilter } from './ConsoleAccountFilter.js';
+```
+
+---
+
+## V1/search/filters (implementations)
+
+```javascript
+// TermFilter.js
+import { Filter } from './Filter.js';
+export class TermFilter extends Filter { constructor(field, value, boost = null) { super('term', field, boost); this.value = value; } }
+
+// TermsFilter.js
+import { Filter, normalizeToArray } from './Filter.js';
+export class TermsFilter extends Filter { constructor(field, value, boost = null) { super('terms', field, boost); this.value = normalizeToArray(value); } }
+
+// NumericFilter.js
+import { Filter } from './Filter.js';
+export class NumericFilter extends Filter { constructor(field, operator, value, boost = null) { super('numeric', field, boost); this.operator = operator; this.value = value; } }
+
+// MatchFilter.js
+import { Filter, normalizeToArray } from './Filter.js';
+export class MatchFilter extends Filter { constructor(field, value, boost = null) { super('match', field, boost); this.value = normalizeToArray(value); } }
+
+// DateFilter.js (dateFrom or dateTo required)
+import { Filter } from './Filter.js';
+export class DateFilter extends Filter { constructor(field, dateFrom = null, dateTo = null, boost = null) { super('date', field, boost); if (dateFrom == null && dateTo == null) throw new Error('DateFilter: dateFrom or dateTo required'); const value = {}; if (dateFrom != null) value.date_from = dateFrom; if (dateTo != null) value.date_to = dateTo; this.value = value; } }
+
+// GeoFilter.js
+import { Filter } from './Filter.js';
+export class GeoFilter extends Filter { constructor(field, value, boost = null) { super('geo', field, boost); this.value = value; } }
+
+// IsNullFilter.js
+import { Filter } from './Filter.js';
+export class IsNullFilter extends Filter { constructor(field, boost = null) { super('is_null', field, boost); } }
+
+// NotNullFilter.js
+import { Filter } from './Filter.js';
+export class NotNullFilter extends Filter { constructor(field, boost = null) { super('not_null', field, boost); } }
+
+// CustomFilter.js
+import { Filter } from './Filter.js';
+export class CustomFilter extends Filter { constructor(field, value, boost = null) { super('custom', field, boost); this.value = value; } }
+
+// GroupBoostFilter.js (lookup_index, field, value, group, min_boost, max_boost, n)
+import { Filter } from './Filter.js';
+export class GroupBoostFilter extends Filter { constructor(lookup_index, field, value, group, min_boost = null, max_boost = null, n = null) { super('group_boost', field, null); this.lookup_index = lookup_index; this.value = value; this.group = group; this.min_boost = min_boost; this.max_boost = max_boost; this.n = n; } }
+
+// TermsLookupFilter.js (path: dot-notation in lookup doc, e.g. "followers.ids")
+import { Filter } from './Filter.js';
+export class TermsLookupFilter extends Filter { constructor(lookup_index, field, value, path, boost = null) { super('terms_lookup', field, boost); this.lookup_index = lookup_index; this.value = value; this.path = path; } }
+
+// ConsoleAccountFilter.js (path: dot-notation in account doc)
+import { Filter } from './Filter.js';
+export class ConsoleAccountFilter extends Filter { constructor(field, value, path, boost = null) { super('console_account', field, boost); this.value = value; this.path = path; } }
+```
+
+---
+
+## V1/features/Features.js
+
+```javascript
+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'];
+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 {
+  _version = 'v1'; _user = null; _items = []; lastCall = null; lastResult = null;
+  constructor(options) {
+    if (!options || typeof options !== 'object') throw new Error('Features: options required');
+    const { url, apiKey, version = 'v1', items = [], userIndex, userId, origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) throw new Error('Features: url required');
+    if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('Features: apiKey required');
+    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 };
+  }
+  getEndpoint() { return `/features/${this._version}`; }
+  getPayload() { return { origin: this._origin, user: this._user, items: this._items.map((item) => ({ ...item })) }; }
+  version(v) { this._version = v; return this; }
+  items(items) { this._items = [...items]; return this; }
+  user(index, userId) { this._user = { index, id: userId }; return this; }
+  async execute() {
+    if (!this._user?.index || !this._user?.id) throw new Error('Features.execute: user must be set');
+    if (!Array.isArray(this._items) || this._items.length === 0) throw new Error('Features.execute: items must be non-empty');
+    const url = `${this._url}${this.getEndpoint()}`;
+    const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` }, body: JSON.stringify(this.getPayload()) });
+    if (!response.ok) throw new Error(`Features API error: ${response.status}`);
+    const result = await response.json();
+    if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error));
+    this.lastCall = { endpoint: this.getEndpoint(), payload: this.getPayload() }; this.lastResult = result;
+    if (!result.result) throw new Error('Features.execute: result.result undefined'); return result.result;
+  }
+  log(string) { this._log(string); }
+  show(results) { this._show(results); }
+}
+```
+
+---
+
+## V1/scoring/Scoring.js
+
+```javascript
+export class Scoring {
+  _userId = null; _itemIds = []; _modelEndpoint = null; lastCall = null; lastResult = null;
+  constructor(options) {
+    if (!options || typeof options !== 'object') throw new Error('Scoring: options required');
+    const { url, apiKey, userId = null, itemIds = [], origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) throw new Error('Scoring: url required');
+    if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('Scoring: apiKey required');
+    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)));
+  }
+  getEndpoint() { if (!this._modelEndpoint?.trim()) throw new Error('Scoring: model(endpoint) required'); return this._modelEndpoint.startsWith('/') ? this._modelEndpoint : `/${this._modelEndpoint}`; }
+  getPayload() { return { origin: this._origin, user_id: this._userId, item_ids: [...this._itemIds] }; }
+  model(endpoint) { this._modelEndpoint = endpoint; return this; }
+  userId(userId) { this._userId = userId; return this; }
+  itemIds(itemIds) { this._itemIds = itemIds; return this; }
+  async execute() {
+    if (!this._modelEndpoint?.trim()) throw new Error('Scoring: model(endpoint) required');
+    if (!this._userId?.trim()) throw new Error('Scoring: user_id required');
+    if (!Array.isArray(this._itemIds) || this._itemIds.length === 0) throw new Error('Scoring: item_ids required');
+    const url = `${this._url}${this.getEndpoint()}`;
+    const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` }, body: JSON.stringify(this.getPayload()) });
+    if (!response.ok) throw new Error(`Scoring API error: ${response.status}`);
+    const result = await response.json();
+    if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error));
+    this.lastCall = { endpoint: this.getEndpoint(), payload: this.getPayload() }; this.lastResult = result;
+    if (result.result === undefined) throw new Error('Scoring: result.result undefined'); return result.result;
+  }
+  log(string) { this._log(string); }
+  show(results) { this._show(results); }
+}
+```
+
+---
+
+## V1/ranking/Ranking.js
+
+```javascript
+export class Ranking {
+  _candidates = []; _sortMethod = 'sort'; _sortParams = null; _diversityMethod = null; _diversityParams = null;
+  _limitsByFieldEnabled = false; _everyN = 10; _limitRules = []; lastCall = null; lastResult = null;
+  constructor(options) {
+    if (!options || typeof options !== 'object') throw new Error('Ranking: options required');
+    const { url, apiKey, candidates = [], origin = 'sdk', log, show } = options;
+    if (typeof url !== 'string' || !url.trim()) throw new Error('Ranking: url required');
+    if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('Ranking: apiKey required');
+    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;
+  }
+  getEndpoint() { return '/ranking/feed'; }
+  _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' || 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) this._limitRules.forEach((r) => r.field && useful.add(r.field));
+    return { usefulFields: useful, needEmbedding };
+  }
+  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?.length) 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;
+  }
+  _buildSortConfig() {
+    if (!this._sortParams) return undefined;
+    if (this._sortMethod === 'sort' && this._sortParams.fields?.length) return { method: 'sort', params: { ...this._sortParams } };
+    if (this._sortMethod === 'linear' && Array.isArray(this._sortParams) && this._sortParams.length) 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) return { method: 'mix', params: this._sortParams.map((p) => ({ field: p.field, direction: p.direction, percentage: p.percentage })) };
+    return undefined;
+  }
+  _buildDiversityConfig() {
+    if (!this._diversityMethod) return undefined;
+    if (this._diversityMethod === 'fields' && this._diversityParams?.fields?.length) return { method: 'fields', params: { fields: [...this._diversityParams.fields] } };
+    if (this._diversityMethod === 'semantic') return { method: 'semantic', params: { lambda: Number(this._diversityParams?.lambda ?? 0.5), horizon: Number(this._diversityParams?.horizon ?? 20) } };
+    return undefined;
+  }
+  _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 })) };
+  }
+  sortingMethod(x) {
+    if (x !== 'sort' && x !== 'linear' && x !== 'mix') throw new Error('Ranking.sortingMethod: sort|linear|mix');
+    this._sortMethod = x;
+    if (x === 'sort') this._sortParams = { fields: [], direction: [] };
+    if (x === 'linear') this._sortParams = [];
+    if (x === 'mix') this._sortParams = [];
+    return this;
+  }
+  sortBy(field, direction = 'desc', field2, direction2 = 'desc') {
+    if (this._sortMethod === 'linear' || this._sortMethod === 'mix') throw new Error('Ranking.sortBy: only for sortingMethod("sort")');
+    this._sortMethod = 'sort';
+    if (!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 required'); if (direction !== 'asc' && direction !== 'desc') throw new Error('Ranking.sortBy: asc|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;
+  }
+  weight(field, w) { if (this._sortMethod !== 'linear') throw new Error('Ranking.weight: only for sortingMethod("linear")'); const f = typeof field === 'string' && field.trim() ? field.trim() : null; if (!f) throw new Error('field required'); if (!Array.isArray(this._sortParams)) this._sortParams = []; this._sortParams.push({ field: f, weight: Number(w) }); return this; }
+  mix(field, direction, percentage) { if (this._sortMethod === 'linear') throw new Error('Ranking.mix: only for sortingMethod("mix")'); 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('field required'); if (direction !== 'asc' && direction !== 'desc') throw new Error('direction asc|desc'); this._sortParams.push({ field: f, direction, percentage: Number(percentage) || 0 }); return this; }
+  diversity(method) { if (method !== 'fields' && method !== 'semantic') throw new Error('Ranking.diversity: fields|semantic'); this._diversityMethod = method; if (method === 'fields') this._diversityParams = { fields: [] }; if (method === 'semantic') this._diversityParams = { lambda: 0.5, horizon: 20 }; return this; }
+  fields(arrayOrItem) { if (this._diversityMethod !== 'fields') throw new Error('Ranking.fields: only for diversity("fields")'); if (!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); }; Array.isArray(arrayOrItem) ? arrayOrItem.forEach(add) : add(arrayOrItem); return this; }
+  horizon(n) { if (this._diversityMethod !== 'semantic') throw new Error('Ranking.horizon: only for diversity("semantic")'); if (!this._diversityParams) this._diversityParams = { lambda: 0.5, horizon: 20 }; this._diversityParams.horizon = Number(n); return this; }
+  lambda(value) { if (this._diversityMethod !== 'semantic') throw new Error('Ranking.lambda: only for diversity("semantic")'); if (!this._diversityParams) this._diversityParams = { lambda: 0.5, horizon: 20 }; this._diversityParams.lambda = Number(value); return this; }
+  limitByField() { this._limitsByFieldEnabled = true; return this; }
+  every(n) { this._everyN = Number(n); return this; }
+  limit(field, max) { const f = typeof field === 'string' && field.trim() ? field.trim() : null; if (!f) throw new Error('limit: field required'); 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; }
+  candidates(candidates) { this._candidates = candidates; return this; }
+  async execute() {
+    if (!Array.isArray(this._candidates) || this._candidates.length === 0) throw new Error('Ranking: candidates required');
+    if (!this._buildSortConfig()) throw new Error('Ranking: sort config required');
+    const url = `${this._url}${this.getEndpoint()}`, payload = this.getPayload();
+    const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` }, body: JSON.stringify(payload) });
+    if (!response.ok) throw new Error(`Ranking API error: ${response.status}`);
+    const result = await response.json();
+    if (result?.error != null) throw new Error(typeof result.error === 'string' ? result.error : String(result.error));
+    if (!result.result) throw new Error('Ranking: result undefined'); return result.result;
+  }
+  log(string) { this._log(string); }
+  show(results) { this._show(results); }
+}
+```
+
+---
+
+## Debugging Tips
+
+- **lastCall / lastResult**: `Search`, `Features`, `Scoring`, and `Ranking` expose `lastCall` (endpoint + payload) and `lastResult` for debugging failed requests.
+- **Semantic diversity**: Ranking with `diversity('semantic')` needs `item_sem_embed2` or `text_vector` on hits; ensure `includeVectors(true)` when searching if you use semantic diversity.
+- **Index canonicalization**: `addFeatures`/addScores use `findIndex(hit._index)`; if your index variant (e.g. `polymarket-items-v2`) is not in `indexOptions`, features/scores may not merge.
+- **Filter boost**: When adding to `boost()` array, all filters except `groupBoost` require a non-null `boost` argument.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbd-studio-sdk",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "SDK for Embed Recommendation Engine APIs",
   "keywords": [
     "web3",
@@ -12,12 +12,19 @@
   ],
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "StudioConfig.js",
-    "V1"
+    "V1",
+    "llms.txt"
   ]
 }