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 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:

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

Response:

{
  "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), then call execute with:

{
  "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)

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.

CLI

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/.

Related tools

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