# Vector rank by cosine

`vector-rank-by-cosine` · version 1.0.0 · Vectors & matrices · free, no key needed

Return the top matching candidate vectors by cosine score, with stable input-order ties.

**Use when you need to: rank vectors by cosine similarity · find closest embeddings by cosine score · top matching vectors for a query embedding.**

## Decide before calling

Read the [versioned contract](/v1/tools/vector-rank-by-cosine/versions/1.0.0) and the supported scope below. Reuse `vector-rank-by-cosine@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `vector-rank-by-cosine@1.0.0` for rank vectors by cosine similarity. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- rank vectors by cosine similarity
- find closest embeddings by cosine score
- top matching vectors for a query embedding
- sort candidate embeddings by angular similarity
- score and rank vectors against one query
- best cosine matches from supplied candidates

## Not supported

- create text embeddings
- search a vector database
- approximate nearest-neighbor indexing

## Behavior

- Query and candidate vectors must be non-empty, equal-length arrays of finite binary64 numbers.
- Each score uses independent index-0-upward sums; higher scores rank first and equal scores retain input order.
- top_k must not exceed the candidate count; omitted candidate ids are returned as null.
- Any zero query or candidate vector produces not_computable.
- Returned numbers are deterministic for this implementation but floating point, not exact decimals.

## Input

- `query` (array of number, required): min items 1; max items 256
- `candidates` (array of object, required): min items 1; max items 128
- `top_k` (number, required): min 1; max 128

## Output

- `ranked` (array of object, required): min items 1; max items 128
- `standard_version` (constant "IEEE 754-2019 binary64; fixed left-to-right order", required)

## Limits

- max input bytes: 32768
- max items: 256
- max candidates: 128
- max total items: 8192
- max id length: 64
- max iterations: 32768
- max output bytes: 24576

## Example

Request input:

```json
{
  "query": [
    1,
    0
  ],
  "candidates": [
    {
      "id": "same",
      "vector": [
        2,
        0
      ]
    },
    {
      "id": "across",
      "vector": [
        0,
        1
      ]
    }
  ],
  "top_k": 1
}
```

Response:

```json
{
  "result": {
    "ranked": [
      {
        "index": 0,
        "id": "same",
        "score": 1
      }
    ],
    "standard_version": "IEEE 754-2019 binary64; fixed left-to-right order"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "vector-rank-by-cosine",
  "version": "1.0.0",
  "input": {
    "query": [
      1,
      0
    ],
    "candidates": [
      {
        "id": "same",
        "vector": [
          2,
          0
        ]
      },
      {
        "id": "across",
        "vector": [
          0,
          1
        ]
      }
    ],
    "top_k": 1
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/vector-rank-by-cosine/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"query":[1,0],"candidates":[{"id":"same","vector":[2,0]},{"id":"across","vector":[0,1]}],"top_k":1}'
```

The machine-readable contract is at [/v1/tools/vector-rank-by-cosine/versions/1.0.0](/v1/tools/vector-rank-by-cosine/versions/1.0.0).

### CLI

```sh
node cli.mjs run vector-rank-by-cosine 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Vector cosine similarity](/tools/vector-cosine-similarity): Return cosine similarity for two decimal-string vectors at a requested precision; reject zero vectors.
- [Vector outer product](/tools/vector-outer-product): Compute the outer product of two finite-number vectors, producing a matrix.
- [Vector scale](/tools/vector-scale): Multiply every entry of a finite-number vector by a scalar.
- [Matrix vector multiply](/tools/matrix-vector-multiply): Multiply an MxN finite-number matrix by a length-N finite-number vector, producing a length-M vector.
- [Vector add](/tools/vector-add): Add two equal-length finite-number vectors elementwise.
- [Vector angle](/tools/vector-angle): Compute the angle in radians between two equal-length finite-number vectors.