mbd-studio-sdk 4.6.4 → 4.6.6

package/llms.txt

@@ -36,12 +36,16 @@ The MBD Studio SDK provides search, features, scoring, and ranking for personali
 | Index | Description |
 |-------|-------------|
 | farcaster-items | Farcaster posts (casts, frames, etc.) |
+| farcaster-users | Farcaster user preference/follow profile (lookup + terms_lookup based personalization) |
 | zora-coins | Zora coins/tokens |
 | polymarket-items | Polymarket prediction markets |
 | polymarket-wallets | Polymarket wallet profiles |
+| token-items | Web3 tokens/instruments |
+| wallet-users | Wallet portfolio + enrichment profile |
 | kalshi-items | Kalshi prediction markets |
+| kalshi-wallets-v20260315 | Kalshi wallet preference/trade profile (UI alias; backend typically uses `kalshi-wallets`) |
 
-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`).
+Canonical names (for features/scores): `farcaster-items`, `zora-coins`, `polymarket-items`, `polymarket-wallets`, `kalshi-items` (used by the SDK's `findIndex()` to attach features/scores). Index aliases may include version suffixes.
 
 ### farcaster-items
 
@@ -75,13 +79,49 @@ Canonical names (for features/scores): `farcaster-items`, `zora-coins`, `polymar
 
 **Filter types:** user_ids, ai_labels2, tags2, is_null, date, numeric_filters
 
-**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)
+**Key fields:** user_id, name, pseudonym, pfp, updated_at, volume, pnl, events_per_day, primary_labels, secondary_labels, primary_tags, secondary_tags, primary_similar_wallets, secondary_similar_wallets, text_vector (lookup fields used by `group_boost`: `label_01`..`label_10`, `tag_01`..`tag_10`)
+
+### farcaster-users
+
+**Sort fields:** updated_at, events_per_day, score_spam, score_not_ok, null
+
+**Filter types:** user_ids, ai_labels2, tags2, is_null, date, numeric_filters
+
+**Key fields:** user_id, name, pseudonym, pfp, updated_at, volume, pnl, events_per_day, primary_labels, secondary_labels, primary_tags, secondary_tags, primary_similar_wallets, secondary_similar_wallets, text_vector
+
+### token-items
+
+**Sort fields:** last_updated, market_cap, price_usd, price_diff_pct_1h, price_diff_pct_1d, volume_usd_1h, volume_usd_1d, volume_usd_24h, total_liquidity_usd, holders_count, circulating_supply, decimals, null
+
+**Filter types:** item_ids, token_identifiers, date, keywords, numeric_filters
+
+**Key fields:** item_id, token_address, symbol, chain, name, last_updated, market_cap, price_usd, price_diff_pct_1d, volume_usd_1d, volume_usd_24h, circulating_supply, decimals
+
+### wallet-users
+
+**Sort fields:** last_trade_timestamp, zerion_last_enriched_at, portfolio_total_usd, portfolio_cash_usd, portfolio_fungibles_usd, portfolio_nfts_usd, pnl_pct_total, pnl_net_invested_usd, pnl_realized_usd, pnl_unrealized_usd, volume_usd_24h, volume_usd_7d, volume_usd_30d, num_trades_24h, num_trades_30d, null
+
+**Filter types:** user_ids, date, numeric_filters
+
+**Key fields:** wallet_address, chains, labels, tags, fungible_positions_tokens_list, last_trade_timestamp, zerion_last_enriched_at, allocation_cash_pct, allocation_fungibles_pct, allocation_nfts_pct, num_trades_24h, num_trades_30d, pnl_net_invested_usd, pnl_pct_total, pnl_realized_usd, pnl_unrealized_usd, portfolio_cash_usd, portfolio_fungibles_usd, portfolio_nfts_usd, portfolio_total_usd, volume_usd_24h, volume_usd_7d, volume_usd_30d
+
+### kalshi-wallets-v20260315
+
+**Sort fields:** updated_at, last_trade_time, pnl, volume_quote, volume_outcome, markets_traded, events_per_day, null
+
+**Filter types:** user_ids, ai_labels2, tags2, is_null, date, numeric_filters
+
+**Key fields:** user_id, updated_at, last_trade_time, pnl, volume_quote, volume_outcome, markets_traded, events_per_day, primary_labels, secondary_labels, primary_tags, secondary_tags, text_vector, sem_embed, protocol
 
 ### kalshi-items
 
 **Sort fields:** created_at, updated_at, volume, start_date, end_date, null
 
-**Filter types:** item_ids, ai_labels, tags, series_category, series_tags, status, ticker, event_id, date, boolean_filters, keywords, numeric_filters
+**Filter types (UI):** item_ids, ai_labels, tags, date, boolean_filters, keywords, numeric_filters
+
+**Boost-only:** boost_wallet_labels, boost_wallet_tags
+
+**Additional term/terms filterable fields (present in index mappings, but not exposed as dedicated UI filter types):** series_category, series_tags, status, ticker, event_id
 
 **Key fields:** item_id, event_id, ticker, question, description, status, active, closed, created_at, updated_at, start_date, end_date, volume, ai_labels_high, ai_labels_med, ai_labels_low, series_category, series_tags, tags, image_url, market_url
 
@@ -119,6 +159,8 @@ Backend: `{ "terms": { field: value } }`
 
 Numeric comparison. Operators: `>`, `>=`, `<`, `<=`.
 
+UI note: the current `NumericFiltersSection` only exposes `>=` and `<=` (frontend restriction); the backend supports all four operators.
+
 ```js
 .include().numeric('volume', '>=', 10000)
 .exclude().numeric('score_spam', '>', 0.5)
@@ -183,7 +225,16 @@ 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.
+Boosts items by group membership from a lookup document (boost endpoint only).
+
+Lookup doc must contain fields at paths `{group}_01`, `{group}_02`, … `{group}_n` (backend formats these as `{group}_{(i+1):02d}`).
+
+For group index `i` (0-based), the backend computes per-group boost:
+
+* if `max_boost == min_boost`: `boost_value = max_boost`
+* else: `boost_value = max_boost - ((max_boost - min_boost) * i / (n - 1))`
+
+It then builds a `bool.should` array with `terms` lookups for each `{group}_XX`, assigning each `terms` clause its own `boost` value (so `group_boost` does not use the per-filter boost multiplier that other boostable filters require).
 
 **Parameters:**
 - `lookup_index` – index containing the lookup doc
@@ -199,7 +250,7 @@ Boosts items by group membership from a lookup document. The lookup doc has path
 .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).
+Backend: `bool.should` + per-group boosted `terms` lookups, with linear interpolation between `max_boost` (group 01) and `min_boost` (group n).
 
 ### terms_lookup
 
@@ -242,6 +293,9 @@ 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: Which numeric operators are supported?**  
+A: The backend accepts `>`, `>=`, `<`, `<=`. The frontend numeric filter UI currently exposes only `>=` and `<=`.
+
 **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`.
 
@@ -761,3 +815,410 @@ export function findIndex(index) {
   return null;
 }
 ```
+
+### package.json
+```json
+{
+  "name": "mbd-studio-sdk",
+  "version": "0.1.0",
+  "description": "SDK for Embed Recommendation Engine APIs",
+  "keywords": [
+    "web3",
+    "AI",
+    "recommendations",
+    "polymarket",
+    "farcaster",
+    "zora"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "StudioConfig.js",
+    "V1",
+    "llms.txt"
+  ],
+  "private": true
+}
+```
+
+### index.d.ts
+```ts
+/**
+ * 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 FrequentValueItem {
+  id: string | number;
+  count: number;
+}
+
+export type FrequentValuesResult = FrequentValueItem[];
+
+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: Array<{ id: string; score: number }>, 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;
+```
+
+### README.md
+```md
+# 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
+
+### Set the target user for personalization
+
+```javascript
+const polymarketWallet = '0x123...';
+mbd.forUser("polymarket-wallets", polymarketWallet);
+```
+
+### 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();
+```
+
+### Add candidates to current context
+
+Attach the search results to the SDK so later steps can use them.
+
+```javascript
+mbd.addCandidates(candidates);
+```
+
+### Enrich your data
+
+Fetch features (signals, metadata) for each candidate.
+
+```javascript
+const features = await mbd.features("v1")
+  .execute();
+mbd.addFeatures(features);
+```
+
+### 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");
+```
+
+### 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 |
+| `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 |
+| `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
+
+- **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/)
+```
+
+### llms.prompt.txt
+```text
+In @ds_frontend/packages/mbd-studio-sdk/llms.txt, concatenate all the source code in @ds_frontend/packages/mbd-studio-sdk 
+and prepare it to be used by AI coding agents.
+
+* Introduction: 
+overall description of the sdk, entry points and typical flows.
+
+* Data catalog: 
+study the frontend in @ds_frontend/app/src and enumerate available indices for searching, 
+and in each one, the different fields and filter types that can be used for filtering or boosting. 
+For kalshi-items, include tags, series_category, series_tags, status, ticker, and event_id.
+
+# Filter types: 
+enumerate the available filter types and provide examples on how to use them.
+Use the implementation details in @ds_search/backend/candidate_generation to understand exactly how the filters work under the hood.
+For numeric filters, make sure you list the available operators.
+For groupBoost filter, make sure you explain how it works and document it enough to be used properly. 
+In general, document all the filters so that the SDK consumers don't need to guess how to use them and which options are available.
+
+* FAQ: 
+Add useful tips that can be useful for consuming the sdk or debugging.
+
+* Source code:
+Decide on the best order to present the files to optimize LLMs performance,
+Then dump the complete source code of the SDK, making it as compact as possible.
+```

package/package.json

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