Building Algorithms Overview

An algorithm is a JavaScript function that defines your recommendation pipeline — how to search for candidates, enrich them with ML features, score them, and rank them into a feed. This page explains how algorithms work and the three ways to create them.

What is an Algorithm?

An algorithm takes user context (like a wallet address or Farcaster FID) and produces a ranked list of items. It runs as a pipeline with up to four stages:

[Search] → [Features] → [Scoring] → [Ranking] → Feed

1. Search — retrieve candidates from an index using filters and boosts
2. Features — enrich candidates with ML signals (topic relevance, user affinity)
3. Scoring — apply a trained model to rerank candidates
4. Ranking — combine signals, apply diversity controls, produce final order

Not every algorithm needs all four stages. A simple trending feed might only use Search + Ranking. A personalized feed uses all four.

Three Ways to Create an Algorithm

1. AI Compose (natural language)

Describe what you want in plain English and the system generates the code:

"Create a feed of trending Polymarket markets about crypto,
personalized to the user's trading history"

The AI Compose endpoint (POST /algo/compose) generates a complete algorithm. You can then edit, validate, and test it.

2. Console Algo Builder

The Console provides a visual editor where you can:

• Write or paste algorithm code in the left panel
• Test with real user inputs in the right panel
• See live preview results
• Validate syntax and security before saving

3. Algorithms DSL (code)

Write algorithms directly using the algo-dsl:

import { StudioConfig, StudioV1 } from 'algo-dsl';

const config = new StudioConfig({ apiKey: process.env.EMBED_API_KEY });
const mbd = new StudioV1({ config });

// Set user context for personalization
mbd.forUser("polymarket-wallets", walletAddress);

// Search
const candidates = await mbd.search()
  .index("polymarket-items")
  .include().numeric("volume_1wk", ">=", 10000)
  .exclude().term("closed", true)
  .execute();
mbd.addCandidates(candidates);

// Features
const features = await mbd.features("v1").execute();
mbd.addFeatures(features);

// Ranking
const ranking = await mbd.ranking()
  .sortingMethod('mix')
  .mix("topic_score", 'desc', 60)
  .mix("user_affinity_score", 'desc', 40)
  .execute();
mbd.addRanking(ranking);

return mbd.getFeed();

The Algorithm Lifecycle

Write code (or AI Compose)
        │
   Validate ──→ syntax + security checks, returns signature
        │
   Test Run ──→ execute in sandbox with real data
        │
   Save ──→ stored as a feed algorithm with algo_id
        │
   Use in Feed Config ──→ bundle with weights, fallbacks, cache
        │
   Serve ──→ production feed delivery

1. Write — create your algorithm code using any of the three methods above
2. Validate — POST /algo/validate checks syntax and security, returns a signature
3. Test — POST /run/algo executes the algorithm in a sandbox with real data
4. Save — POST /deploy/algos saves the algorithm with a name and description
5. Deploy — create a Feed Config that uses your algorithm
6. Serve — call POST /deploy/serve with the config ID to deliver feeds

See Validate & Test for the full workflow.

Pipeline Stages in Detail

What's Next

• Search → Retrieve candidates with filters, boosts, and semantic search
• Quickstart: Algorithms DSL → Full walkthrough building a Polymarket feed
• Feed Configs → Bundle algorithms into deployable configs