mbd-studio-sdk 3.3.0 → 3.4.1

package/README.md

@@ -19,13 +19,13 @@ const mbd = new StudioV1({ config });
 
 ## Usage
 
-### 1. Set the target user for personalization
+### Set the target user for personalization
 ```javascript
 const polymarketWallet = '0x123...';
 mbd.forUser("polymarket-wallets", polymarketWallet);
 ```
 
-### 2. Generate candidates
+### Generate candidates
 
 Search your mbd indices using inclide/exclude filters and boosting options.
 
@@ -44,7 +44,7 @@ const candidates = await mbd.search()
   .execute();
 ```
 
-### 2. Add candidates to current context
+### Add candidates to current context
 
 Attach the search results to the SDK so later steps can use them.
 
@@ -52,7 +52,7 @@ Attach the search results to the SDK so later steps can use them.
 mbd.addCandidates(candidates);
 ```
 
-### 3. Enrich your data
+### Enrich your data
 
 Fetch features (signals, metadata) for each candidate.
 
@@ -62,7 +62,7 @@ const features = await mbd.features("v1")
 mbd.addFeatures(features);
 ```
 
-### 4. Run predictive and reranking AI models
+### Run predictive and reranking AI models
 
 Score candidates with ML models for relevance or reranking.
 
@@ -73,7 +73,7 @@ const scores = await mbd.scoring()
 mbd.addScores(scores, "rerank_polymkt1");
 ```
 
-### 5. Combine all the data into final recommendations
+### Combine all the data into final recommendations
 
 Merge signals and produce the final ranked list with diversity and limits.
 
@@ -99,6 +99,7 @@ mbd.addRanking(ranking);
 |--------|-------------|
 | `forUser(index, userId)` | Set user context for personalization |
 | `search()` | Build and run a search query |
+| `frequentValues(index, field, size?)` | Fetch frequent values in an index/field (default size: 25) |
 | `addCandidates(array)` | Add search hits to the current context |
 | `features(version)` | Fetch features for candidates |
 | `addFeatures(result)` | Attach features to candidates |
@@ -109,5 +110,5 @@ mbd.addRanking(ranking);
 
 ## Useful links
 
-- **Demo repo:** [https://github.com/ZKAI-Network/mbd_studio_demo](https://github.com/ZKAI-Network/mbd_studio_demo)
-- **Studio webapp:** [https://api.mbd.xyz/v3/studio/frontend/](https://api.mbd.xyz/v3/studio/frontend/)
+- **Examples:** [https://github.com/ZKAI-Network/mbd_studio_demo](https://github.com/ZKAI-Network/mbd_studio_demo)
+- **Embed Studio webapp:** [https://api.mbd.xyz/v3/studio/frontend/](https://api.mbd.xyz/v3/studio/frontend/)

package/V1/Studio.js

@@ -33,6 +33,9 @@ export class Studio {
       show: this._show,
     });
   }
+  async frequentValues(index, field, size = 25) {
+    return this.search().index(index).frequentValues(field, size);
+  }
   addCandidates(array) {
     this._candidates.push(...array);
   }
@@ -142,6 +145,7 @@ export class Studio {
     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);

package/V1/search/Search.js

@@ -123,6 +123,39 @@ export class Search {
     this._log(`  max_score: ${infos.max_score}`);
     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 (call index(name) first)');
+    }
+    if (typeof field !== 'string' || !field.trim()) {
+      throw new Error('Search.frequentValues: field must be a non-empty string');
+    }
+    const n = Number(size);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error('Search.frequentValues: size must be a positive integer');
+    }
+    const endpoint = `/search/frequent_values/${encodeURIComponent(this._index)}/${encodeURIComponent(field.trim())}?size=${n}`;
+    const url = `${this._url}${endpoint}`;
+    this.log(`GET ${url}`);
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${this._apiKey}` },
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      let message = `Search frequentValues error: ${response.status} ${response.statusText}`;
+      if (text) message += ` — ${text}`;
+      this.log(message);
+      throw new Error(message);
+    }
+    const result = await response.json();
+    if (result && typeof result.error !== 'undefined' && result.error !== null) {
+      const msg = typeof result.error === 'string' ? result.error : String(result.error);
+      this.log(msg);
+      throw new Error(msg);
+    }
+    return result;
+  }
   async lookup(docId) {
     if (!this._index || typeof this._index !== 'string' || !this._index.trim()) {
       throw new Error('Search.lookup: index must be set (call index(name) first)');

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "mbd-studio-sdk",
-  "version": "3.3.0",
-  "description": "SDK for MBD Studio backend services",
+  "version": "3.4.1",
+  "description": "SDK for Embed Recommendation Engine APIs",
+  "keywords": [
+    "web3",
+    "AI",
+    "recommendations",
+    "polymarket",
+    "farcaster",
+    "zora"
+  ],
   "type": "module",
   "main": "index.js",
   "exports": {