mbd-studio-sdk 4.1.5 → 4.2.0

package/llms.txt

@@ -1,42 +1,276 @@
-# MBD Studio SDK – Reference for AI Coding Agents
+# MBD Studio SDK – LLM Reference
+
+## Introduction
+
+The MBD Studio SDK provides search, features, scoring, and ranking for personalized feeds. It targets Elasticsearch-backed indices and MBD backend services.
+
+**Entry points:**
+- `StudioConfig({ apiKey, commonUrl?, servicesUrl? })` – API configuration
+- `StudioV1({ config })` or `StudioV1({ apiKey, commonUrl })` – main client
+- `studio.search()` – search builder
+- `studio.features(version)` – feature fetcher
+- `studio.scoring()` – scoring/reranking
+- `studio.ranking()` – ranking with diversity/limits
+
+**Typical flow:**
+1. `forUser(index, userId)` – set user context for personalization
+2. `search().index(name).include()/exclude()/boost().<filters>.execute()` – get candidates
+3. `addCandidates(hits)` – attach to context
+4. `features().execute()` → `addFeatures(result)` – enrich with signals
+5. `scoring().model(endpoint).execute()` → `addScores(result, key)` – ML scores
+6. `ranking().sortBy(...).execute()` → `addRanking(result)` – final ordering
+7. `getFeed()` – retrieve ranked items
+
+**Search endpoint selection (automatic):**
+- `esQuery()` → `/search/es_query` (raw ES query)
+- `text()` or `vector()` → `/search/semantic` (no filters)
+- `boost()` filters present → `/search/boost`
+- else → `/search/filter_and_sort`
 
-## Overview
+---
+
+## Data Catalog
+
+### Indices
+
+| Index | Description |
+|-------|-------------|
+| farcaster-items | Farcaster posts (casts, frames, etc.) |
+| zora-coins | Zora coins/tokens |
+| polymarket-items | Polymarket prediction markets |
+| polymarket-wallets | Polymarket wallet profiles |
+| kalshi-items | Kalshi prediction markets |
+
+Canonical names (for features/scores): `farcaster-items`, `zora-coins`, `polymarket-items`, `polymarket-wallets`, `kalshi-items`. Index aliases may include version suffixes (e.g. `farcaster-items-v2`).
+
+### farcaster-items
+
+**Sort fields:** item_creation_timestamp, score_popular, score_trending, num_follower, score_reaction, item_id, null
+
+**Filter types:** user_preferences, ai_labels, coin_labels, authors, author_followed_by, publication_types, channels, domains, apps, languages, keywords, locations, miniapps, video, item_features, date, spam_moderation, social_filters, beacon_models, blacklist, custom_json
+
+**Key fields:** user_id, type (cast, image, video, etc.), text_enriched, domains, lang, channels, item_creation_timestamp, score_spam, score_not_ok, num_like, num_comment, num_share, num_follower, score_popular, score_trending, score_reaction, ai_labels_high/med/low
+
+### zora-coins
+
+**Sort fields:** score_popular, score_trending, num_buy, num_sell, zora_market_cap, zora_price_in_usdc, zora_total_supply, zora_total_volume, zora_unique_holders, zora_volume_24h, num_follower, zora_created_at, zora_updated_at, last_interaction_timestamp, null
+
+**Filter types:** ai_labels, date, publication_types, media_content_types, domains, authors, author_followed_by, market_info, spam_moderation, keywords, is_null, boolean_filters
+
+**Key fields:** zora_name, zora_description, zora_creator_farcaster_id, user_name, domain, zora_media_content_type, active, zora_updated_at, total_volume, volume_24h, price_usdc, market_cap, unique_holders, total_supply
+
+### polymarket-items
+
+**Sort fields:** created_at, updated_at, liquidity, volume, volume_24hr, volume_1wk, volume_1mo, volume_1yr, one_hour_price_change_abs, one_day_price_change_abs, one_week_price_change_abs, one_month_price_change_abs, spread, null
+
+**Filter types:** item_ids, wallet_prefs1, ai_labels, tags, date, boolean_filters, keywords, numeric_filters
+
+**Boost-only:** boost_wallet_labels, boost_wallet_tags
 
-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).
+**Key fields:** created_at, updated_at, start_date, end_date, game_start_time, liquidity, volume, volume_24hr, volume_1wk, volume_1mo, volume_1yr, span_days, featured, restricted, closed, price_under05_or_over95, price_0_or_1, ai_labels_med, tags
 
-## Entry Points
+### polymarket-wallets
 
-- `StudioConfig` – API config (apiKey required; commonUrl or servicesUrl for endpoints)
-- `StudioV1` – Main client. Import: `import { StudioConfig, StudioV1 } from 'mbd-studio-sdk'`
+**Sort fields:** updated_at, pnl, volume, null
 
-## Typical Flow
+**Filter types:** user_ids, ai_labels2, tags2, is_null, date, numeric_filters
 
-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
+**Key fields:** user_id, name, pseudonym, pfp, updated_at, volume, pnl, events_per_day, ai_labels_med, tags (label_01..label_10, tag_01..tag_10)
 
-**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.
+### kalshi-items
+
+**Sort fields:** created_at, updated_at, volume, start_date, end_date, null
+
+**Filter types:** item_ids, ai_labels, date, boolean_filters, keywords, numeric_filters
+
+**Key fields:** question, description, created_at, updated_at, start_date, end_date, volume, active, closed
 
 ---
 
-## index.js
+## Filter Types
 
-```javascript
-import * as V1 from './V1/index.js';
-export { StudioConfig } from './StudioConfig.js';
-export const StudioV1 = V1.Studio;
+All filters require `include()`, `exclude()`, or `boost()` to be called first. Filters in `include` → ES `must`; `exclude` → ES `must_not`; `boost` → ES `should`. For `boost`, non–group_boost filters require a non-null boost value.
+
+### term
+
+Exact match on a single value.
+
+```js
+.include().term('type', 'cast')
+.exclude().term('closed', true)
+.boost().term('lang', 'en', 1.5)
+```
+
+Backend: `{ "term": { field: { "value": value } } }`
+
+### terms
+
+Match any of multiple values. Value can be array or comma-separated string.
+
+```js
+.include().terms('channels', ['/base', '/degen'])
+.terms('user_id', '123,456,789')  // normalized to array
+.boost().terms('ai_labels_med', ['crypto', 'defi'], 2)
+```
+
+Backend: `{ "terms": { field: value } }`
+
+### numeric
+
+Numeric comparison. Operators: `>`, `>=`, `<`, `<=`.
+
+```js
+.include().numeric('volume', '>=', 10000)
+.exclude().numeric('score_spam', '>', 0.5)
+.boost().numeric('num_follower', '>=', 1000, 1.2)
+```
+
+Backend: `{ "range": { field: { gt|gte|lt|lte: value } } }`
+
+### date
+
+Date range. At least one of dateFrom or dateTo required. ISO strings or Elasticsearch date math (e.g. `now-7d`, `now/d`).
+
+```js
+.include().date('item_creation_timestamp', 'now-7d', 'now')
+.include().date('created_at', '2024-01-01', null)
+.exclude().date('updated_at', null, 'now-30d')
+```
+
+Backend: `{ "range": { field: { gte?: date_from, lte?: date_to } } }`
+
+### match
+
+Full-text match on keywords. Value normalized to array; each keyword is a separate match clause, OR’d together.
+
+```js
+.include().match('text_enriched', 'crypto defi')
+.include().match('zora_name', ['bitcoin', 'ethereum'])
+```
+
+Backend: `{ "bool": { "should": [ { "match": { field: keyword } } for each ], "minimum_should_match": 1 } }`
+
+### geo
+
+Geo-distance filter. Value: array of strings `"geo:lat,lon"`. Default distance: 100km.
+
+```js
+.include().geo('location', ['geo:40.7128,-74.0060', 'geo:37.7749,-122.4194'])
 ```
 
+Backend: `{ "bool": { "should": [ { "geo_distance": { "distance": "100km", field: { lat, lon } } } ], "minimum_should_match": 1 } }`
+
+### is_null / not_null
+
+Check if field is missing or present.
+
+```js
+.include().isNull('zora_creator_farcaster_id')
+.exclude().notNull('pfp')
+```
+
+Backend: is_null → `{ "bool": { "must_not": [ { "exists": { "field" } } ] } }`; not_null → `{ "exists": { "field" } }`
+
+### custom
+
+Raw Elasticsearch filter clause. Value is the clause object.
+
+```js
+.include().custom('_', { "script": { "script": { "source": "..." } } })
+```
+
+Backend: `value` is used as-is.
+
+### group_boost
+
+Boosts items by group membership from a lookup document. The lookup doc has paths `{group}_01`, `{group}_02`, … `{group}_n`. Items matching `{group}_01` get max_boost; `{group}_02` get slightly less; etc. Linear decay from max to min over n groups.
+
+**Parameters:**
+- `lookup_index` – index containing the lookup doc
+- `field` – field on the main index to match against
+- `value` – document ID in lookup_index
+- `group` – prefix for path (e.g. `"label"` → label_01, label_02, …)
+- `min_boost` – boost for last group (default 1)
+- `max_boost` – boost for first group (default 5)
+- `n` – number of groups (default 10)
+
+```js
+.boost().groupBoost('polymarket-wallets', 'ai_labels_med', walletId, 'label', 1, 5, 10)
+.boost().groupBoost('polymarket-wallets', 'tags', walletId, 'tag', 1, 3, 5)
+```
+
+Backend: builds `bool.should` with `terms` lookup per group path, each with its own boost (linear interpolation).
+
+### terms_lookup
+
+Filter by terms fetched from another document. Fetches `path` from doc `value` in `lookup_index`, matches `field`.
+
+```js
+.include().termsLookup('following-graph', 'user_id', farcasterFid, 'following')
+.include().termsLookup('user-prefs', 'ai_labels_med', userId, 'preferred_labels')
+```
+
+Backend: `{ "terms": { field: { "index": lookup_index, "id": value, "path": path } } }`
+
+### console_account
+
+Lookup terms from console-accounts index. Used for blacklists, whitelists, etc.
+
+```js
+.exclude().consoleAccount('user_id', consoleAccountId, 'exclude_user_ids')
+.include().consoleAccount('item_id', consoleAccountId, 'include_item_ids')
+```
+
+Backend: `{ "terms": { field: { "index": "console-accounts", "id": value, "path": path } } }`
+
+---
+
+## FAQ
+
+**Q: Why do I get "call include(), exclude(), or boost() before adding filters"?**  
+A: You must call one of these before any filter. They set which array (include/exclude/boost) the next filters go into.
+
+**Q: Can I use filters with semantic search?**  
+A: No. Semantic search (`text()` or `vector()`) uses `/search/semantic` and does not support include/exclude/boost. Use filter_and_sort or boost for filtering.
+
+**Q: Can I sort when using boost?**  
+A: No. Boost endpoint does not support `sortBy()`. Use filter_and_sort if you need sorting.
+
+**Q: What is the difference between term and terms?**  
+A: `term` matches a single value exactly. `terms` matches any value in a list.
+
+**Q: What is the difference between term and match?**  
+A: `term` is exact (keyword-like). `match` is full-text (analyzed, OR across keywords).
+
+**Q: How does group_boost work with polymarket-wallets?**  
+A: A wallet doc has `label_01`, `label_02`, … (or `tag_01`, …) with preferred labels/tags. Items matching label_01 get highest boost; label_02 get less; etc. Use `group` = `"label"` or `"tag"` and `field` = `ai_labels_med` or `tags`.
+
+**Q: onlyIds, selectFields, includeVectors – can I use more than one?**  
+A: No. They are mutually exclusive.
+
+**Q: How do I debug a failing query?**  
+A: Use `search.lastCall` (endpoint + payload) and `search.lastResult` after `execute()`. Enable `log` in config to see requests/results.
+
+**Q: Index names with versions?**  
+A: Use base names like `farcaster-items`; backend may resolve to versioned aliases. `findIndex()` maps versioned names to canonical base for features/scores.
+
 ---
 
-## StudioConfig.js
+## Source Code
 
-```javascript
+Order: entry → config → Studio → Search → Filter base → filters → Features → Scoring → Ranking → utils.
+
+---
+
+### index.js
+```js
+import * as V1 from './V1/index.js';
+export { StudioConfig } from './StudioConfig.js';
+export const StudioV1 = V1.Studio;
+```
+
+### StudioConfig.js
+```js
 const defaultBaseUrl = 'https://api.mbd.xyz/v3/studio';
 export class StudioConfig {
   constructor(options) {
@@ -52,8 +286,7 @@ export class StudioConfig {
       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(/\/$/, ''));
+      [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;
     }
@@ -64,32 +297,13 @@ export class StudioConfig {
 }
 ```
 
----
-
-## V1/index.js
-
-```javascript
+### V1/index.js
+```js
 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
+### V1/Studio.js
+```js
 import { StudioConfig } from '../StudioConfig.js';
 import { Search } from './search/Search.js';
 import { Features, sortAvailableFeatures } from './features/Features.js';
@@ -114,8 +328,7 @@ export class Studio {
   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 }));
+    const items = (this._candidates && this._candidates.length > 0) ? 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) {
@@ -129,57 +342,51 @@ export class Studio {
       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;
+      if (hit._features) for (const [k, v] of Object.entries(hit._features)) if (typeof v === 'number' && !Number.isNaN(v)) availableFeatures[k] = true;
+      if (hit._scores) for (const [k, v] of Object.entries(hit._scores)) if (typeof v === 'number' && !Number.isNaN(v)) availableScores[k] = 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) : [];
+    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 });
   }
   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]; }
+    if (!this._candidates || !scoringResult || !Array.isArray(scoringResult)) return;
+    const rankToScore = {}; scoringResult.forEach((id, i) => { rankToScore[id] = 1.0 - (i / scoringResult.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;
+    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];
     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; }
+  dropFeatures() { for (const c of this._candidates) delete c._features; }
+  dropVectors() { const keys = ['text_vector', 'item_sem_embed', 'item_sem_embed2']; for (const c of this._candidates) { const src = c._source; if (src) for (const k of keys) delete src[k]; } }
+  transform(fn) { this._candidates = this._candidates.map(fn); }
+  log(s) { this._log(s); }
+  show(results) { this._show(results === undefined ? this._candidates : results); }
 }
 ```
 
----
-
-## V1/search/Search.js
-
-```javascript
+### V1/search/Search.js
+```js
 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;
+  _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);
+    this._url = url.trim().replace(/\/$/, ''); this._apiKey = apiKey.trim(); this._origin = 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';
@@ -196,10 +403,7 @@ export class Search {
     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 (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;
@@ -211,60 +415,52 @@ export class Search {
     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()');
+    if (endpoint === '/search/semantic') { if (this._include.length || this._exclude.length || this._boost.length) throw new Error('Search: semantic does not support filters'); if (this._sort_by) throw new Error('Search: semantic does not support sortBy'); }
+    if (endpoint === '/search/boost' && this._sort_by) throw new Error('Search: boost does not support sortBy');
     const payload = this.getPayload(), url = `${this._url}${endpoint}`;
-    this.log(`Sending request to ${url}`);
+    this.log(`Sending request to ${url}`); this.log(`Payload:\n${JSON.stringify(payload, null, 2)}`);
     const startTime = performance.now();
     const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` }, body: JSON.stringify(payload) });
-    if (!response.ok) { const text = await response.text(); throw new Error(`Search API error: ${response.status} — ${text}`); }
+    if (!response.ok) { const text = await response.text(); throw new Error(`Search API error: ${response.status} ${response.statusText}${text ? ' — ' + 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;
+    result.took_sdk = Math.round(performance.now() - startTime); this.lastCall = { endpoint, payload }; this.lastResult = result;
+    const res = result.result; if (!res) throw new Error('Search.execute: result.result is undefined');
+    this._log(`Search result: total_hits=${res?.total_hits ?? 0} fetched=${res?.hits?.length ?? 0} took_es=${res?.took_es ?? 0} took_backend=${res?.took_backend ?? 0}`);
+    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}` } });
+    const n = Number(size); if (!Number.isInteger(n) || n <= 0) throw new Error('Search.frequentValues: size must be a positive integer');
+    const url = `${this._url}/search/frequent_values/${encodeURIComponent(this._index)}/${encodeURIComponent(field.trim())}?size=${n}`;
+    const response = await fetch(url, { 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;
+    const result = await response.json(); if (result?.error != null) throw new 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 (!this._index || typeof this._index !== 'string' || !docId?.trim()) throw new Error('Search.lookup: index and docId required');
+    const url = `${this._url}/search/document/${encodeURIComponent(this._index)}/${encodeURIComponent(docId.trim())}`;
+    const response = await fetch(url, { 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;
+    const result = await response.json(); if (result?.error != null) throw new 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; }
+  size(size) { const n = Number(size); if (!Number.isInteger(n) || n <= 0 || n >= 2000) throw new Error('Search.size: must be 1..1999'); 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; }
+  selectFields(fields) { if (fields === null) { this._select_fields = null; return this; } if (!Array.isArray(fields)) throw new Error('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; }
+  vector(vector) { if (!Array.isArray(vector)) throw new Error('Search.vector: array'); this._vector = vector; return this; }
+  esQuery(rawQuery) { if (rawQuery == null || typeof rawQuery !== 'object' || Array.isArray(rawQuery)) throw new Error('esQuery: plain object'); this._es_query = rawQuery; return this; }
+  sortBy(field, direction = 'desc') { if (typeof field !== 'string' || !field.trim()) throw new Error('sortBy: field required'); if (direction !== 'asc' && direction !== 'desc') throw new Error('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;
-  }
+  filter(f) { this._requireActiveArray(); if (!(f instanceof Filter)) throw new Error('filter must be Filter instance'); if (this._active_array === this._boost && f.filter !== 'group_boost' && f.boost == null) throw new Error('boost array: filter needs boost'); this._active_array.push(f); 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; }
@@ -277,16 +473,13 @@ export class Search {
   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); }
+  log(s) { this._log(s); }
   show(results) { this._show(results); }
 }
 ```
 
----
-
-## V1/search/filters/Filter.js
-
-```javascript
+### V1/search/filters/Filter.js
+```js
 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];
@@ -300,215 +493,217 @@ export class Filter {
 }
 ```
 
----
-
-## 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
+### V1/search/filters/TermFilter.js
+```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
+### V1/search/filters/TermsFilter.js
+```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
+### V1/search/filters/NumericFilter.js
+```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)
+### V1/search/filters/DateFilter.js
+```js
 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; } }
+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');
+    this.value = {}; if (dateFrom != null) this.value.date_from = dateFrom; if (dateTo != null) this.value.date_to = dateTo;
+  }
+}
+```
 
-// GeoFilter.js
+### V1/search/filters/GeoFilter.js
+```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
+### V1/search/filters/MatchFilter.js
+```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); } }
+```
+
+### V1/search/filters/IsNullFilter.js
+```js
 import { Filter } from './Filter.js';
 export class IsNullFilter extends Filter { constructor(field, boost = null) { super('is_null', field, boost); } }
+```
 
-// NotNullFilter.js
+### V1/search/filters/NotNullFilter.js
+```js
 import { Filter } from './Filter.js';
 export class NotNullFilter extends Filter { constructor(field, boost = null) { super('not_null', field, boost); } }
+```
 
-// CustomFilter.js
+### V1/search/filters/CustomFilter.js
+```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)
+### V1/search/filters/GroupBoostFilter.js
+```js
 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; } }
+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")
+### V1/search/filters/TermsLookupFilter.js
+```js
 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)
+### V1/search/filters/ConsoleAccountFilter.js
+```js
 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
+### V1/search/filters/index.js
+```js
+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';
+```
 
-```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'];
+### V1/features/Features.js
+```js
+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];
+  const preferred = PREFERRED_FEATURE_COLUMNS.filter((c) => available.includes(c));
+  const rest = available.filter((c) => !PREFERRED_FEATURE_COLUMNS.includes(c));
+  const regular = rest.filter((c) => !c.startsWith('AI:') && !c.startsWith('TAG:')).sort();
+  const ai = rest.filter((c) => c.startsWith('AI:')).sort();
+  const tag = rest.filter((c) => c.startsWith('TAG:')).sort();
+  return [...preferred, ...regular, ...ai, ...tag];
 }
 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 };
+    if (!url?.trim() || !apiKey?.trim()) throw new Error('Features: url and apiKey required');
+    this._url = url.trim().replace(/\/$/, ''); this._apiKey = apiKey.trim(); this._version = version; this._origin = origin?.trim() || 'sdk';
+    this._log = typeof log === 'function' ? log : console.log; this._show = typeof show === 'function' ? show : console.log;
+    this._items = Array.isArray(items) && items.length > 0 ? items : []; this._user = (userIndex != null && userId != null) ? { index: userIndex, id: userId } : null;
   }
-  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;
+    if (!this._user?.index || !this._user?.id) throw new Error('Features: user required');
+    if (!this._items.length) throw new Error('Features: items required');
+    const url = `${this._url}/features/${this._version}`;
+    const payload = { origin: this._origin, user: this._user, items: this._items.map((i) => ({ ...i })) };
+    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(`Features API: ${response.status}`);
+    const result = await response.json(); if (result?.error != null) throw new Error(String(result.error));
+    return result.result;
   }
-  log(string) { this._log(string); }
-  show(results) { this._show(results); }
+  log(s) { this._log(s); }
+  show(r) { this._show(r); }
 }
 ```
 
----
-
-## V1/scoring/Scoring.js
-
-```javascript
+### V1/scoring/Scoring.js
+```js
 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)));
+    if (!url?.trim() || !apiKey?.trim()) throw new Error('Scoring: url and apiKey required');
+    this._url = url.trim().replace(/\/$/, ''); this._apiKey = apiKey.trim(); this._origin = origin?.trim() || 'sdk';
+    this._log = typeof log === 'function' ? log : console.log; this._show = typeof show === 'function' ? show : console.log;
+    this._userId = userId?.trim() || null; this._itemIds = Array.isArray(itemIds) && itemIds.length > 0 ? itemIds.map((id) => String(id)) : []; this._modelEndpoint = null;
   }
-  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; }
+  userId(id) { this._userId = id; return this; }
+  itemIds(ids) { this._itemIds = [...ids]; return this; }
   async execute() {
-    if (!this._modelEndpoint?.trim()) throw new Error('Scoring: model(endpoint) required');
+    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;
+    if (!this._itemIds.length) throw new Error('Scoring: item_ids required');
+    const path = this._modelEndpoint.startsWith('/') ? this._modelEndpoint : `/${this._modelEndpoint}`;
+    const url = `${this._url}${path}`;
+    const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this._apiKey}` }, body: JSON.stringify({ origin: this._origin, user_id: this._userId, item_ids: this._itemIds }) });
+    if (!response.ok) throw new Error(`Scoring API: ${response.status}`);
+    const result = await response.json(); if (result?.error != null) throw new Error(String(result.error));
+    return result.result;
   }
-  log(string) { this._log(string); }
-  show(results) { this._show(results); }
+  log(s) { this._log(s); }
+  show(r) { this._show(r); }
 }
 ```
 
----
-
-## V1/ranking/Ranking.js
-
-```javascript
+### V1/ranking/Ranking.js
+```js
 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;
+    if (!url?.trim() || !apiKey?.trim()) throw new Error('Ranking: url and apiKey required');
+    this._url = url.trim().replace(/\/$/, ''); this._apiKey = apiKey.trim(); this._origin = origin?.trim() || 'sdk'; this._candidates = candidates;
+    this._sortMethod = 'sort'; this._sortParams = null; this._diversityMethod = null; this._diversityParams = null; this._limitsByFieldEnabled = false; this._everyN = 10; this._limitRules = [];
+    this._log = typeof log === 'function' ? log : console.log; this._show = typeof show === 'function' ? show : console.log;
   }
-  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 };
+  sortingMethod(x) {
+    if (!['sort','linear','mix'].includes(x)) throw new Error('sortingMethod: sort|linear|mix');
+    this._sortMethod = x;
+    if (x === 'sort') this._sortParams = { fields: [], direction: [] };
+    if (x === 'linear' || x === 'mix') this._sortParams = [];
+    return this;
   }
-  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;
+  sortBy(field, direction = 'desc', field2, direction2 = 'desc') {
+    if (this._sortMethod !== 'sort') throw new Error('sortBy only for sort method');
+    this._sortMethod = 'sort'; this._sortParams = this._sortParams || { fields: [], direction: [] };
+    if (!field?.trim()) throw new Error('sortBy: field required');
+    if (!['asc','desc'].includes(direction)) throw new Error('sortBy: asc|desc');
+    this._sortParams = { fields: [field.trim()], direction: [direction] };
+    if (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('weight only for linear'); if (!Array.isArray(this._sortParams)) this._sortParams = []; this._sortParams.push({ field: field?.trim(), weight: Number(w) }); return this; }
+  mix(field, direction, percentage) { if (this._sortMethod === 'linear') throw new Error('mix not for linear'); this._sortMethod = 'mix'; if (!Array.isArray(this._sortParams)) this._sortParams = []; this._sortParams.push({ field: field?.trim(), direction, percentage: Number(percentage) || 0 }); return this; }
+  diversity(method) { if (!['fields','semantic'].includes(method)) throw new Error('diversity: fields|semantic'); this._diversityMethod = method; this._diversityParams = method === 'fields' ? { fields: [] } : { lambda: 0.5, horizon: 20 }; return this; }
+  fields(arr) { if (this._diversityMethod !== 'fields') throw new Error('fields only for diversity(fields)'); if (!this._diversityParams?.fields) this._diversityParams = { fields: [] }; (Array.isArray(arr) ? arr : [arr]).forEach((n) => { const s = n?.trim(); if (s && !this._diversityParams.fields.includes(s)) this._diversityParams.fields.push(s); }); return this; }
+  horizon(n) { if (this._diversityMethod !== 'semantic') throw new Error('horizon only for semantic'); (this._diversityParams = this._diversityParams || {}).horizon = Number(n); return this; }
+  lambda(v) { if (this._diversityMethod !== 'semantic') throw new Error('lambda only for semantic'); (this._diversityParams = this._diversityParams || {}).lambda = Number(v); return this; }
+  limitByField() { this._limitsByFieldEnabled = true; return this; }
+  every(n) { this._everyN = Number(n); return this; }
+  limit(field, max) { const f = field?.trim(); if (!f) throw new Error('limit: field required'); const r = this._limitRules.find((x) => x.field === f); if (r) r.limit = Number(max) || 0; else this._limitRules.push({ field: f, limit: Number(max) || 0 }); return this; }
+  candidates(c) { this._candidates = c; return this; }
+  async execute() {
+    if (!Array.isArray(this._candidates) || !this._candidates.length) throw new Error('Ranking: candidates required');
+    const sortConfig = this._buildSortConfig(); if (!sortConfig) throw new Error('Ranking: sort config required');
+    const payload = this.getPayload(); const url = `${this._url}/ranking/feed`;
+    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: ${response.status}`);
+    const result = await response.json(); if (result?.error != null) throw new Error(String(result.error));
+    return result.result;
   }
   _buildSortConfig() {
     if (!this._sortParams) return undefined;
@@ -528,54 +723,41 @@ export class Ranking {
     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;
+  _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 };
   }
-  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;
+  getPayload() {
+    const { usefulFields, needEmbedding } = this._getUsefulFieldsAndNeedEmbedding();
+    const items = (this._candidates || []).map((hit) => {
+      const item = { item_id: hit._id };
+      for (const k of usefulFields) { const v = hit._features?.[k] ?? hit._scores?.[k]; if (v !== undefined) item[k] = 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 divConfig = this._buildDiversityConfig(); if (divConfig) payload.diversity = divConfig;
+    const limConfig = this._buildLimitsByFieldConfig(); if (limConfig) payload.limits_by_field = limConfig;
+    return payload;
   }
-  log(string) { this._log(string); }
-  show(results) { this._show(results); }
+  log(s) { this._log(s); }
+  show(r) { this._show(r); }
 }
 ```
 
----
-
-## 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.
+### V1/utils/indexUtils.js
+```js
+export function findIndex(index) {
+  const options = ['farcaster-items', 'zora-coins', 'polymarket-items', 'polymarket-wallets', 'kalshi-items'];
+  for (const opt of options) if (index?.startsWith(opt)) return opt;
+  return null;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbd-studio-sdk",
-  "version": "4.1.5",
+  "version": "4.2.0",
   "description": "SDK for Embed Recommendation Engine APIs",
   "keywords": [
     "web3",