# Vector cosine similarity

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

Return cosine similarity for two decimal-string vectors at a requested precision; reject zero vectors.

**Use when you need to: calculate cosine similarity · compare two numeric vectors · find vector angle similarity.**

## Decide before calling

Read the [versioned contract](/v1/tools/vector-cosine-similarity/versions/1.0.0) and the supported scope below. Reuse `vector-cosine-similarity@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-cosine-similarity@1.0.0` for calculate 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

- calculate cosine similarity
- compare two numeric vectors
- find vector angle similarity
- cosine score to significant digits
- measure embedding direction similarity
- compare decimal string vectors

## Not supported

- cosine distance matrix
- sparse vector parsing

## Behavior

- Dot products and squared norms are exact rationals; only the final square root is rounded.
- similarity has the requested significant digits using half-even rounding; either zero vector is not_computable.

## Input

- `a` (array of string, required): min items 1; max items 256; each min length 1; each max length 128
- `b` (array of string, required): min items 1; max items 256; each min length 1; each max length 128
- `significant_digits` (integer, required): min 2; max 15
- `rounding` (one of "half_even", required)

## Output

- `standard_version` (constant "packet-r90-dot-over-euclidean-norms-1.0.0", required)
- `similarity` (string, required)
- `significant_digits` (integer, required)
- `rounding` (string, required)

## Limits

- max input bytes: 16384
- max items: 256
- max decimal chars: 128
- max output bytes: 16384
- max sqrt iterations: 6

## Example

Request input:

```json
{
  "a": [
    "1",
    "0"
  ],
  "b": [
    "0",
    "1"
  ],
  "significant_digits": 4,
  "rounding": "half_even"
}
```

Response:

```json
{
  "result": {
    "standard_version": "packet-r90-dot-over-euclidean-norms-1.0.0",
    "similarity": "0",
    "significant_digits": 4,
    "rounding": "half_even"
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "vector-cosine-similarity",
  "version": "1.0.0",
  "input": {
    "a": [
      "1",
      "0"
    ],
    "b": [
      "0",
      "1"
    ],
    "significant_digits": 4,
    "rounding": "half_even"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/vector-cosine-similarity/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"a":["1","0"],"b":["0","1"],"significant_digits":4,"rounding":"half_even"}'
```

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

### CLI

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

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

## Related tools

- [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.
- [Vector approx equal](/tools/vector-approx-equal): Compare two equal-length finite-number vectors for approximate equality within an absolute tolerance.
- [Vector dot](/tools/vector-dot): Compute the dot (scalar) product of two equal-length finite-number vectors.
- [Vector lerp](/tools/vector-lerp): Linearly interpolate (or extrapolate) between two equal-length finite-number vectors.
- [Vector outer product](/tools/vector-outer-product): Compute the outer product of two finite-number vectors, producing a matrix.