# Rank borda aggregate

`rank-borda-aggregate` · version 1.0.0 · Optimization & voting · free, no key needed

Aggregate weighted complete or partial rankings into exact Borda scores, rank groups, and audit contributions.

**Use when you need to: aggregate weighted Borda rankings · calculate Borda count scores · combine partial preference rankings.**

## Decide before calling

Read the [versioned contract](/v1/tools/rank-borda-aggregate/versions/1.0.0) and the supported scope below. Reuse `rank-borda-aggregate@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 `rank-borda-aggregate@1.0.0` for aggregate weighted Borda rankings. 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

- aggregate weighted Borda rankings
- calculate Borda count scores
- combine partial preference rankings
- audit weighted rank votes
- group tied Borda results
- score ranked choice ballots
- deterministic ranking aggregation

## Not supported

- instant-runoff voting
- Condorcet pairwise winners
- rankings with tied positions
- negative or fractional ballot weights

## Behavior

- For N candidates, a listed candidate at zero-based position p receives N - 1 - p base points, multiplied by the ranking weight.
- unranked_policy "zero" gives omitted candidates 0 points; "last_place" gives each omitted candidate max(N - listed_count - 1, 0) points.
- Candidate identifiers are exact, non-empty, well-formed strings; duplicates and ranked identifiers absent from candidates are invalid_input.
- Scores, candidates within groups, and each contribution points array use Unicode code-point lexicographic order.
- Rank groups use descending score and competition ranks: after a tie of two at rank 1, the next group has rank 3.

## Input

- `candidates` (array of string, required): min items 1; max items 100; each min length 1; each max length 64
- `rankings` (array of object, required): min items 1; max items 100
- `unranked_policy` (one of "zero", "last_place", required)

## Output

- `scores` (array of object, required): min items 1; max items 100
- `rank_groups` (array of object, required): min items 1; max items 100
- `contributions` (array of object, required): min items 1; max items 100

## Limits

- max candidates: 100
- max rankings: 100
- max candidate chars: 64
- max weight: 1000

## Example

Request input:

```json
{
  "candidates": [
    "alice",
    "bob",
    "carol"
  ],
  "rankings": [
    {
      "ranking": [
        "alice",
        "bob",
        "carol"
      ],
      "weight": 2
    },
    {
      "ranking": [
        "carol",
        "bob",
        "alice"
      ],
      "weight": 1
    }
  ],
  "unranked_policy": "zero"
}
```

Response:

```json
{
  "result": {
    "scores": [
      {
        "candidate": "alice",
        "score": 4
      },
      {
        "candidate": "bob",
        "score": 3
      },
      {
        "candidate": "carol",
        "score": 2
      }
    ],
    "rank_groups": [
      {
        "rank": 1,
        "score": 4,
        "candidates": [
          "alice"
        ]
      },
      {
        "rank": 2,
        "score": 3,
        "candidates": [
          "bob"
        ]
      },
      {
        "rank": 3,
        "score": 2,
        "candidates": [
          "carol"
        ]
      }
    ],
    "contributions": [
      {
        "ranking_index": 0,
        "weight": 2,
        "points": [
          {
            "candidate": "alice",
            "points": 2,
            "weighted_points": 4
          },
          {
            "candidate": "bob",
            "points": 1,
            "weighted_points": 2
          },
          {
            "candidate": "carol",
            "points": 0,
            "weighted_points": 0
          }
        ]
      },
      {
        "ranking_index": 1,
        "weight": 1,
        "points": [
          {
            "candidate": "alice",
            "points": 0,
            "weighted_points": 0
          },
          {
            "candidate": "bob",
            "points": 1,
            "weighted_points": 1
          },
          {
            "candidate": "carol",
            "points": 2,
            "weighted_points": 2
          }
        ]
      }
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "rank-borda-aggregate",
  "version": "1.0.0",
  "input": {
    "candidates": [
      "alice",
      "bob",
      "carol"
    ],
    "rankings": [
      {
        "ranking": [
          "alice",
          "bob",
          "carol"
        ],
        "weight": 2
      },
      {
        "ranking": [
          "carol",
          "bob",
          "alice"
        ],
        "weight": 1
      }
    ],
    "unranked_policy": "zero"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/rank-borda-aggregate/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"candidates":["alice","bob","carol"],"rankings":[{"ranking":["alice","bob","carol"],"weight":2},{"ranking":["carol","bob","alice"],"weight":1}],"unranked_policy":"zero"}'
```

The machine-readable contract is at [/v1/tools/rank-borda-aggregate/versions/1.0.0](/v1/tools/rank-borda-aggregate/versions/1.0.0).

### CLI

```sh
node cli.mjs run rank-borda-aggregate 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [Vote condorcet winner](/tools/vote-condorcet-winner): Compute weighted pairwise counts, a strict Condorcet winner, and the generalized Smith set.
- [Assignment hungarian solve](/tools/assignment-hungarian-solve): Solve a bounded rectangular integer minimum-cost assignment with explicit unmatched costs.
- [Knapsack 01 solve](/tools/knapsack-01-solve): Solve bounded 0/1 knapsack exactly and return the optimum value, weight, and lexicographically smallest index list.
- [Pareto front find](/tools/pareto-front-find): Find stable nondominated row indices and a domination witness for every excluded row using exact rational criteria.
- [Round robin schedule generate](/tools/round-robin-schedule-generate): Generate a deterministic single or double round-robin schedule with ordered rounds, home/away assignments, and byes.