# Bleu brevity penalty

`bleu-brevity-penalty` · version 1.0.0 · Text · free, no key needed

Compute the BLEU corpus brevity penalty from candidate and reference lengths using closest reference lengths.

**Use when you need to: BLEU brevity penalty from token lengths · effective reference length r for a test corpus · best match reference length closest to the candidate.**

## Decide before calling

Read the [versioned contract](/v1/tools/bleu-brevity-penalty/versions/1.0.0) and the supported scope below. Reuse `bleu-brevity-penalty@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 `bleu-brevity-penalty@1.0.0` for BLEU brevity penalty from token lengths. 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

- BLEU brevity penalty from token lengths
- effective reference length r for a test corpus
- best match reference length closest to the candidate
- exp(1 - r/c) penalty for short translations
- is my translation too short for BLEU
- corpus brevity penalty with several references per segment
- קנס קיצור לתרגום קצר מדי

## Not supported

- counting tokens in raw text (lengths must be given as integers)
- shortest-reference or average-reference length variants
- per-sentence penalties averaged over a corpus
- the full BLEU score (use bleu-corpus-compute)

## Behavior

- Each segment gives candidate_length and 1 to 8 reference_lengths. Its best-match length is the reference length closest to candidate_length; ties go to the shorter length (mteval-v13a, NLTK closest_ref_length, sacreBLEU).
- candidate_length c and reference_length r are the corpus sums of candidate lengths and best-match lengths (Papineni 2002 section 2.2.2); closest_reference_lengths lists the best-match length per segment in input order.
- brevity_penalty = 1 when c > r; 0 when c = 0 (an empty candidate, even when r = 0, as in NLTK brevity_penalty); otherwise exp(1 - r/c), which is 1 when c = r.
- decimals (0-15) rounds brevity_penalty with Number.prototype.toFixed (nearest, computed on the exact binary value); omitted means full IEEE-754 double precision.

## Input

- `segments` (array of object, required): min items 1; max items 10000
- `decimals` (integer, optional): min 0; max 15

## Output

- `candidate_length` (integer, required): min 0
- `reference_length` (integer, required): min 0
- `closest_reference_lengths` (array of integer, required): min items 1; each min 0
- `brevity_penalty` (number, required): min 0; max 1

## Limits

- max segments: 10000
- max references per segment: 8
- max length value: 1000000

## Example

Request input:

```json
{
  "segments": [
    {
      "candidate_length": 12,
      "reference_lengths": [
        28,
        28
      ]
    }
  ]
}
```

Response:

```json
{
  "result": {
    "candidate_length": 12,
    "reference_length": 28,
    "closest_reference_lengths": [
      28
    ],
    "brevity_penalty": 0.2635971381157267
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "bleu-brevity-penalty",
  "version": "1.0.0",
  "input": {
    "segments": [
      {
        "candidate_length": 12,
        "reference_lengths": [
          28,
          28
        ]
      }
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/bleu-brevity-penalty/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"segments":[{"candidate_length":12,"reference_lengths":[28,28]}]}'
```

The machine-readable contract is at [/v1/tools/bleu-brevity-penalty/versions/1.0.0](/v1/tools/bleu-brevity-penalty/versions/1.0.0).

### CLI

```sh
node cli.mjs run bleu-brevity-penalty 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [Bleu corpus compute](/tools/bleu-corpus-compute): Compute canonical corpus BLEU from pre-tokenized segments: score, brevity penalty, lengths, clipped n-gram counts.
- [Bleu ngrams count](/tools/bleu-ngrams-count): Count BLEU clipped n-gram matches and totals per order for tokenized segments, with optional clipping tables.
- [Bleu sentence components](/tools/bleu-sentence-components): Extract sentence BLEU statistics: clipped matches, n-gram totals, candidate and closest reference length.
- [Chrf plus plus compute](/tools/chrf-plus-plus-compute): Compute exact chrF++ (character 6-grams plus word 1-2-grams, Popovic 2017) with the word tokens it scored.
- [Bleu sentence compute](/tools/bleu-sentence-compute): Compute sentence-level BLEU for one tokenized hypothesis with a chosen smoothing method (none or Chen-Cherry 1-3).
- [Chrf compute](/tools/chrf-compute): Compute exact chrF (character 6-gram F-beta, Popovic 2015) for hypothesis/reference segments, corpus and per segment.