Max Marginal Relevance

Overview

You send candidates with relevance scores and either a symmetric similarities matrix or vectors (cosine). lambda defaults to 0.5 and limit defaults to 10 (at most 200). The first pick is the highest relevance; later picks maximise lambda * relevance minus (1-lambda) times the maximum similarity to the selected set. Ties break on lexical id. Zero vectors and asymmetric matrices are refused. This does not embed text or learn lambda.

A second hit that is almost the first hit wastes the context window.

When to use it

Scope

Non-goals

• Does not generate embeddings
• Does not learn lambda
• Does not retrieve documents

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"knowledge.max_marginal_relevance","input":{"candidates":[{"id":"a","relevance":1.0},{"id":"b","relevance":0.9}],"similarities":[[1,0.2],[0.2,1]],"limit":1}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("knowledge.max_marginal_relevance", {"limit":2,"candidates":[{"id":"a","relevance":1},{"id":"b","relevance":0.9},{"id":"c","relevance":0.8}],"similarities":[[1,0.99,0.1],[0.99,1,0.1],[0.1,0.1,1]]});

Errors

Other limits

Limitations

• Does not generate embeddings
• Does not learn lambda
• Does not retrieve documents
• Embedding the documents
• Approximate nearest-neighbour search

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "knowledge.max_marginal_relevance",
  "input": {
    "limit": 2,
    "candidates": [
      {
        "id": "a",
        "relevance": 1
      },
      {
        "id": "b",
        "relevance": 0.9
      },
      {
        "id": "c",
        "relevance": 0.8
      }
    ],
    "similarities": [
      [
        1,
        0.99,
        0.1
      ],
      [
        0.99,
        1,
        0.1
      ],
      [
        0.1,
        0.1,
        1
      ]
    ]
  }
}

Examples

{
  "limit": 2,
  "candidates": [
    {
      "id": "a",
      "relevance": 1
    },
    {
      "id": "b",
      "relevance": 0.9
    },
    {
      "id": "c",
      "relevance": 0.8
    }
  ],
  "similarities": [
    [
      1,
      0.99,
      0.1
    ],
    [
      0.99,
      1,
      0.1
    ],
    [
      0.1,
      0.1,
      1
    ]
  ]
}

{
  "selected": [
    {
      "rank": 1,
      "id": "a",
      "relevance": 1,
      "redundancy": 0,
      "mmr": 0.5
    },
    {
      "rank": 2,
      "id": "c",
      "relevance": 0.8,
      "redundancy": 0.1,
      "mmr": 0.35
    }
  ],
  "similarity": "SUPPLIED_MATRIX",
  "truncated": true,
  "candidateCount": 3,
  "lambda": 0.5,
  "limit": 2,
  "formulaVersion": "knowledge.max_marginal_relevance.v1"
}

{
  "limit": 1,
  "candidates": [
    {
      "relevance": 0.2,
      "id": "low",
      "vector": [
        1,
        0
      ]
    },
    {
      "relevance": 0.9,
      "id": "high",
      "vector": [
        0,
        1
      ]
    }
  ],
  "lambda": 1
}

{
  "selected": [
    {
      "rank": 1,
      "id": "high",
      "relevance": 0.9,
      "redundancy": 0,
      "mmr": 0.9
    }
  ],
  "similarity": "COSINE",
  "truncated": true,
  "candidateCount": 2,
  "lambda": 1,
  "limit": 1,
  "formulaVersion": "knowledge.max_marginal_relevance.v1"
}

Recommended use cases

• Drop a near-duplicate after the top hit
• Keep only relevance when lambda is 1

Avoid for

• Embedding the documents
• Approximate nearest-neighbour search

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags