# Bleu sentence components

`bleu-sentence-components` · version 1.0.0 · Text · free, no key needed

Extract sentence BLEU statistics: clipped matches, n-gram totals, candidate and closest reference length.

**Use when you need to: sentence BLEU statistics for one hypothesis · matched and total n-grams of a single translation · hypothesis length and closest reference length for BLEU.**

## Decide before calling

Read the [versioned contract](/v1/tools/bleu-sentence-components/versions/1.0.0) and the supported scope below. Reuse `bleu-sentence-components@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-sentence-components@1.0.0` for sentence BLEU statistics for one hypothesis. 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

- sentence BLEU statistics for one hypothesis
- matched and total n-grams of a single translation
- hypothesis length and closest reference length for BLEU
- clipping table of one sentence against its references
- inputs for BLEU smoothing from tokenized sentence
- why did my sentence get a low BLEU
- רכיבי ציון התרגום של משפט אחד

## Not supported

- the BLEU score itself (use bleu-sentence-compute or bleu-smoothing-compute)
- smoothed counts (bleu-smoothing-compute applies Chen and Cherry smoothing)
- tokenizing, lowercasing or normalizing raw text
- statistics summed over a multi-sentence corpus (deep10-bleu-corpus)

## Behavior

- hypothesis is one token list and references 1 to 8 token lists; tokens are compared by exact string equality (no case folding, no Unicode normalization). max_order omitted means 4.
- matches[n-1] = sum over distinct hypothesis n-grams g of min(count(g), largest count of g in any single reference); totals[n-1] = max(0, c - n + 1) (Papineni 2002 section 2.1).
- candidate_length c = number of hypothesis tokens; reference_length r = the reference length closest to c, ties to the shorter (mteval-v13a, NLTK, sacreBLEU).
- include_ngrams omitted means false. With true, ngrams lists every distinct hypothesis n-gram with count, max_reference_count and clipped_count, ordered by order then first occurrence; output over 1,000,000 UTF-8 bytes is limit_exceeded.
- The statistics are exactly the matches/totals/candidate_length/reference_length inputs of bleu-smoothing-compute.

## Input

- `hypothesis` (array of string, required): each min length 1; each max length 128
- `references` (array of array of string, required): min items 1; max items 8; each each min length 1; each each max length 128
- `max_order` (integer, optional): min 1; max 8
- `include_ngrams` (boolean, optional)

## Output

- `candidate_length` (integer, required): min 0
- `reference_length` (integer, required): min 0
- `max_order` (integer, required): min 1; max 8
- `matches` (array of integer, required): min items 1; max items 8; each min 0
- `totals` (array of integer, required): min items 1; max items 8; each min 0
- `ngrams` (array of object, optional)

## Limits

- max references: 8
- max total tokens: 10000
- max token bytes: 128
- max total token bytes: 262144
- max output bytes: 1000000

## Example

Request input:

```json
{
  "hypothesis": [
    "am",
    "I",
    "am",
    "a",
    "character",
    "sequence"
  ],
  "references": [
    [
      "I",
      "am",
      "a",
      "symbol",
      "string",
      "sequence",
      "a",
      "a"
    ]
  ]
}
```

Response:

```json
{
  "result": {
    "candidate_length": 6,
    "reference_length": 8,
    "max_order": 4,
    "matches": [
      4,
      2,
      1,
      0
    ],
    "totals": [
      6,
      5,
      4,
      3
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "bleu-sentence-components",
  "version": "1.0.0",
  "input": {
    "hypothesis": [
      "am",
      "I",
      "am",
      "a",
      "character",
      "sequence"
    ],
    "references": [
      [
        "I",
        "am",
        "a",
        "symbol",
        "string",
        "sequence",
        "a",
        "a"
      ]
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/bleu-sentence-components/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"hypothesis":["am","I","am","a","character","sequence"],"references":[["I","am","a","symbol","string","sequence","a","a"]]}'
```

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

### CLI

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

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

## Related tools

- [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 compute](/tools/bleu-sentence-compute): Compute sentence-level BLEU for one tokenized hypothesis with a chosen smoothing method (none or Chen-Cherry 1-3).
- [Bleu corpus compute](/tools/bleu-corpus-compute): Compute canonical corpus BLEU from pre-tokenized segments: score, brevity penalty, lengths, clipped n-gram counts.
- [Bleu brevity penalty](/tools/bleu-brevity-penalty): Compute the BLEU corpus brevity penalty from candidate and reference lengths using closest reference lengths.
- [Chrf compute](/tools/chrf-compute): Compute exact chrF (character 6-gram F-beta, Popovic 2015) for hypothesis/reference segments, corpus and per segment.
- [Bleu smoothing compute](/tools/bleu-smoothing-compute): Apply none or Chen-Cherry smoothing 1-3 to BLEU match/total counts; return smoothed counts, BP and BLEU.