mbd-studio-sdk 3.2.0 → 3.3.0

package/README.md

@@ -0,0 +1,113 @@
+# mbd-studio-sdk
+
+SDK for MBD Studio backend services — search, features, scoring, and ranking.
+
+## Install
+
+```bash
+npm install mbd-studio-sdk
+```
+
+## Setup
+
+```javascript
+import { StudioConfig, StudioV1 } from 'mbd-studio-sdk';
+
+const config = new StudioConfig({ apiKey: 'YOUR_API_KEY' });
+const mbd = new StudioV1({ config });
+```
+
+## Usage
+
+### 1. Set the target user for personalization
+```javascript
+const polymarketWallet = '0x123...';
+mbd.forUser("polymarket-wallets", polymarketWallet);
+```
+
+### 2. Generate candidates
+
+Search your mbd indices using inclide/exclude filters and boosting options.
+
+```javascript
+const candidates = await mbd.search()
+  .index("polymarket-items")
+  .includeVectors(true)
+  .include()
+  .numeric("volume_1wk", ">=", 10000)
+  .exclude()
+  .term("closed", true)
+  .term("price_under05_or_over95", true)
+  .boost()
+  .groupBoost("polymarket-wallets", "ai_labels_med", polymarketWallet, "label", 1, 5, 10)
+  .groupBoost("polymarket-wallets", "tags", polymarketWallet, "tag", 1, 5, 10)
+  .execute();
+```
+
+### 2. Add candidates to current context
+
+Attach the search results to the SDK so later steps can use them.
+
+```javascript
+mbd.addCandidates(candidates);
+```
+
+### 3. Enrich your data
+
+Fetch features (signals, metadata) for each candidate.
+
+```javascript
+const features = await mbd.features("v1")
+  .execute();
+mbd.addFeatures(features);
+```
+
+### 4. Run predictive and reranking AI models
+
+Score candidates with ML models for relevance or reranking.
+
+```javascript
+const scores = await mbd.scoring()
+  .model("/scoring/ranking_model/polymarket-rerank-v1")
+  .execute();
+mbd.addScores(scores, "rerank_polymkt1");
+```
+
+### 5. Combine all the data into final recommendations
+
+Merge signals and produce the final ranked list with diversity and limits.
+
+```javascript
+const ranking = await mbd.ranking()
+  .sortingMethod('mix')
+  .mix("topic_score", 'desc', 40)
+  .mix("user_affinity_score", 'desc', 40)
+  .mix("rerank_polymkt1", 'desc', 20)
+  .diversity('semantic')
+  .lambda(0.5)
+  .horizon(20)
+  .limitByField()
+  .every(10)
+  .limit("cluster_1", 1)
+  .execute();
+mbd.addRanking(ranking);
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `forUser(index, userId)` | Set user context for personalization |
+| `search()` | Build and run a search query |
+| `addCandidates(array)` | Add search hits to the current context |
+| `features(version)` | Fetch features for candidates |
+| `addFeatures(result)` | Attach features to candidates |
+| `scoring()` | Run scoring/reranking models |
+| `addScores(result, key)` | Attach model scores to candidates |
+| `ranking()` | Produce final ranked recommendations |
+| `addRanking(result)` | Attach ranking scores to candidates |
+
+## 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/)

package/StudioConfig.js

@@ -1,3 +1,6 @@
+const defaultBaseUrl = 'https://api.mbd.studio/v3/studio';
+
+
 export class StudioConfig {
   constructor(options) {
     if (!options || typeof options !== 'object') {
@@ -15,10 +18,7 @@ export class StudioConfig {
       this.featuresService = url;
       this.scoringService = url;
       this.rankingService = url;
-    } else {
-      if (!servicesUrl || typeof servicesUrl !== 'object') {
-        throw new Error('StudioConfig: when commonUrl is not provided, servicesUrl must be an object with searchService, storiesService, featuresService, scoringService, rankingService');
-      }
+    } 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)
@@ -32,6 +32,12 @@ export class StudioConfig {
       this.featuresService = featuresService.trim().replace(/\/$/, '');
       this.scoringService = scoringService.trim().replace(/\/$/, '');
       this.rankingService = rankingService.trim().replace(/\/$/, '');
+    } else {
+      this.searchService = defaultBaseUrl;
+      this.storiesService = defaultBaseUrl;
+      this.featuresService = defaultBaseUrl;
+      this.scoringService = defaultBaseUrl;
+      this.rankingService = defaultBaseUrl;
     }
     this.apiKey = apiKey.trim();
     this.log = typeof log === 'function' ? log : console.log.bind(console);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbd-studio-sdk",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "SDK for MBD Studio backend services",
   "type": "module",
   "main": "index.js",