> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# max_marginal_relevance_search

Returns documents selected using maximal marginal relevance to balance relevance and diversity.

<Note>Available in Embedded and JS/TS SDK. The Python SDK does not currently support MMR search.</Note>

<Tabs>
  <Tab title="Embedded">
    ```python theme={null}
    max_marginal_relevance_search(
        query: str,
        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    ### Parameters

    | Parameter     | Type                       | Description                                                            |
    | ------------- | -------------------------- | ---------------------------------------------------------------------- |
    | `query`       | `str`                      | Query text to search for                                               |
    | `k`           | `int`                      | Number of documents to return (default: 4)                             |
    | `fetch_k`     | `int`                      | Number of documents to fetch before reranking (default: 20)            |
    | `lambda_mult` | `float`                    | Diversity control: 0 = max diversity, 1 = min diversity (default: 0.5) |
    | `filter`      | `Optional[Dict[str, Any]]` | *(Optional)* Metadata filters to apply                                 |
    | `**kwargs`    | `Any`                      | Additional keyword arguments (currently unused)                        |

    ### Returns

    `List[Document]`: List of diverse, relevant Document objects

    ### Example Usage

    ```python theme={null}
    # Search with balanced relevance and diversity
    results = store.max_marginal_relevance_search(
        "Python programming concepts",
        k=5,
        fetch_k=20,
        lambda_mult=0.5  # Balance relevance and diversity
    )

    # Maximum diversity (avoid similar documents)
    diverse_results = store.max_marginal_relevance_search(
        "data structures",
        k=5,
        lambda_mult=0.0  # Maximum diversity
    )

    # Maximum relevance (similar to standard search)
    relevant_results = store.max_marginal_relevance_search(
        "algorithms",
        k=5,
        lambda_mult=1.0  # Maximum relevance
    )
    ```

    ### By Vector Variant

    The Embedded library also provides `max_marginal_relevance_search_by_vector` for searching with a pre-computed embedding vector:

    ```python theme={null}
    max_marginal_relevance_search_by_vector(
        embedding: Union[List[float], np.ndarray],
        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        filter: Optional[Dict[str, Any]] = None,
        **kwargs
    ) -> List[Document]
    ```

    **Parameters:**

    | Parameter     | Type                             | Description                                                            |
    | ------------- | -------------------------------- | ---------------------------------------------------------------------- |
    | `embedding`   | `Union[List[float], np.ndarray]` | Query embedding vector                                                 |
    | `k`           | `int`                            | Number of documents to return (default: 4)                             |
    | `fetch_k`     | `int`                            | Number of documents to fetch before reranking (default: 20)            |
    | `lambda_mult` | `float`                          | Diversity control: 0 = max diversity, 1 = min diversity (default: 0.5) |
    | `filter`      | `Optional[Dict[str, Any]]`       | *(Optional)* Metadata filters to apply                                 |
    | `**kwargs`    | `Any`                            | Additional keyword arguments (currently unused)                        |

    **Example:**

    ```python theme={null}
    # Get query embedding
    query_embedding = store.get_embeddings("machine learning algorithms")

    # MMR search with embedding
    results = store.max_marginal_relevance_search_by_vector(
        query_embedding,
        k=5,
        fetch_k=30,
        lambda_mult=0.3  # Favor diversity
    )

    # With metadata filter
    filtered_results = store.max_marginal_relevance_search_by_vector(
        query_embedding,
        k=4,
        filter={"category": "tutorial"},
        lambda_mult=0.7  # Favor relevance
    )
    ```
  </Tab>

  <Tab title="JS/TS">
    ```typescript theme={null}
    maxMarginalRelevanceSearch(
        query: string,
        options: { k?: number; fetchK?: number; lambda?: number; filter?: Record<string, any> }
    ): Promise<Document[]>
    ```

    ### Parameters

    | Parameter        | Type                  | Description                                                          |
    | ---------------- | --------------------- | -------------------------------------------------------------------- |
    | `query`          | `string`              | Query text to search for                                             |
    | `options.k`      | `number`              | *(Optional)* Number of documents to return                           |
    | `options.fetchK` | `number`              | *(Optional)* Number of documents to fetch before reranking           |
    | `options.lambda` | `number`              | *(Optional)* Diversity control: 0 = max diversity, 1 = min diversity |
    | `options.filter` | `Record<string, any>` | *(Optional)* Metadata filters to apply                               |

    ### Returns

    `Promise<Document[]>`: Array of diverse, relevant Document objects

    <Note>The JS/TS SDK does not have a separate by-vector variant. Use `maxMarginalRelevanceSearch` with a text query.</Note>

    ### Example Usage

    ```typescript theme={null}
    const results = await store.maxMarginalRelevanceSearch(
        "Python programming concepts",
        { k: 5, fetchK: 20, lambda: 0.5 }
    );

    // Maximum diversity
    const diverse = await store.maxMarginalRelevanceSearch(
        "data structures",
        { k: 5, lambda: 0.0 }
    );
    ```
  </Tab>
</Tabs>

### Async

<Accordion title="Python async variants">
  The Embedded library provides an async version of this method prefixed with `a`:

  ```python theme={null}
  # amax_marginal_relevance_search — async variant
  docs = await store.amax_marginal_relevance_search("query", k=5, lambda_mult=0.5)
  ```
</Accordion>

<Note>
  JS/TS methods are natively async — all signatures above already return `Promise<...>`. No separate async variant is needed.
</Note>