Skip to content

docs: align Quality Evaluation API with the current contract #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tn819 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: align Quality Evaluation API with the current contract #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 67 additions & 58 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6479,7 +6479,7 @@
}
}
},
"/v1/quality-evaluation": {
"/v1/quality-evaluations": {
"post": {
"tags": [
"QualityEvaluation"
Expand Down Expand Up @@ -6532,7 +6532,7 @@
},
"example": {
"job_id": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19",
"poll_url": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19"
"poll_url": "/v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19"
}
}
}
Expand Down Expand Up @@ -6574,7 +6574,7 @@
]
}
},
"/v1/quality-evaluation/{job_id}": {
"/v1/quality-evaluations/{job_id}": {
"get": {
"tags": [
"QualityEvaluation"
Expand All @@ -6587,7 +6587,7 @@
"name": "job_id",
"in": "path",
"required": true,
"description": "The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID.",
"description": "The job identifier returned by `POST /v1/quality-evaluations`. Must be a valid UUID.",
"schema": {
"type": "string",
"format": "uuid",
Expand Down Expand Up @@ -6635,7 +6635,9 @@
}
]
}
]
],
"source": "Our Q3 revenue came in 5% above forecast.",
"target": "Unser Q3-Umsatz lag 5 % unter der Prognose."
},
{
"segment_index": 1,
Expand Down Expand Up @@ -6671,23 +6673,11 @@
}
]
}
]
}
],
"summary": {
"overall_score": 72,
"granular_counts": {
"Accuracy": {
"Mistranslation": {
"Critical": 1,
"Minor": 1
},
"Omission": {
"Major": 1
}
}
],
"source": "Please share these results with your teams by Friday.",
"target": "Bitte teilen Sie diese Ergebnisse mit Ihrem Team."
}
}
]
}
}
}
Expand Down Expand Up @@ -10841,6 +10831,16 @@
"type": "string",
"description": "Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs).",
"example": "de"
},
"glossary_ids": {
"type": "array",
"description": "Optional glossary IDs to include when evaluating the segments. Empty values are rejected.",
"items": {
"type": "string"
},
"example": [
"def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
]
}
}
},
Expand Down Expand Up @@ -10883,13 +10883,13 @@
"job_id": {
"type": "string",
"format": "uuid",
"description": "The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result.",
"description": "The job identifier. Use it with `GET /v1/quality-evaluations/{job_id}` to poll for the result.",
"example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19"
},
"poll_url": {
"type": "string",
"description": "Relative URL you can use to poll for the result.",
"example": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19"
"example": "/v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19"
}
}
},
Expand Down Expand Up @@ -10920,8 +10920,7 @@
"required": [
"job_id",
"status",
"segments",
"summary"
"segments"
],
"properties": {
"job_id": {
Expand All @@ -10942,39 +10941,6 @@
"items": {
"$ref": "#/components/schemas/QualityEvaluationSegment"
}
},
"summary": {
"type": "object",
"required": [
"overall_score",
"granular_counts"
],
"description": "Aggregate quality results across all segments.",
"properties": {
"overall_score": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary).",
"example": 72
},
"granular_counts": {
"type": "object",
"description": "Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts.",
"additionalProperties": true,
"example": {
"Accuracy": {
"Mistranslation": {
"Critical": 1,
"Minor": 1
},
"Omission": {
"Major": 1
}
}
}
}
}
}
}
},
Expand Down Expand Up @@ -11032,6 +10998,23 @@
"description": "Zero-based index matching the position of this segment in the request.",
"example": 0
},
"source": {
"type": "string",
"description": "Source text echoed from the evaluation pipeline. Omitted when empty.",
"example": "Our Q3 revenue came in 5% above forecast."
},
"target": {
"type": "string",
"description": "Target text echoed from the evaluation pipeline. Omitted when empty.",
"example": "Unser Q3-Umsatz lag 5 % unter der Prognose."
},
"entries": {
"type": "array",
"description": "Glossary matches applied to this segment. Omitted when there are no matches.",
"items": {
"$ref": "#/components/schemas/QualityEvaluationGlossaryEntry"
}
},
"errors": {
"type": "array",
"description": "Quality issues identified in this segment. Empty if no issues were found.",
Expand All @@ -11041,6 +11024,32 @@
}
}
},
"QualityEvaluationGlossaryEntry": {
"type": "object",
"required": [
"source_entry",
"target_entry"
],
"properties": {
"source_entry": {
"type": "string",
"description": "Glossary source term.",
"example": "revenue"
},
"target_entry": {
"type": "string",
"description": "Glossary target term.",
"example": "Umsatz"
},
"ranges": {
"type": "array",
"description": "Half-open `[start, end)` spans on the segment target text where this match applies.",
"items": {
"$ref": "#/components/schemas/QualityEvaluationSpan"
}
}
}
},
"QualityEvaluationIssue": {
"type": "object",
"required": [
Expand Down
89 changes: 49 additions & 40 deletions api-reference/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4508,7 +4508,7 @@ paths:
$ref: '#/components/responses/NotFound'
"429":
$ref: '#/components/responses/TooManyRequests'
/v1/quality-evaluation:
/v1/quality-evaluations:
post:
tags:
- QualityEvaluation
Expand Down Expand Up @@ -4546,7 +4546,7 @@ paths:
$ref: '#/components/schemas/QualityEvaluationJobCreated'
example:
job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
poll_url: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
poll_url: /v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
400:
description: |-
Request validation failed. Common causes:
Expand Down Expand Up @@ -4575,7 +4575,7 @@ paths:
$ref: '#/components/responses/TooManyRequests'
security:
- auth_header: [ ]
/v1/quality-evaluation/{job_id}:
/v1/quality-evaluations/{job_id}:
get:
tags:
- QualityEvaluation
Expand All @@ -4587,7 +4587,7 @@ paths:
- name: job_id
in: path
required: true
description: The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID.
description: The job identifier returned by `POST /v1/quality-evaluations`. Must be a valid UUID.
schema:
type: string
format: uuid
Expand All @@ -4607,6 +4607,8 @@ paths:
status: done
segments:
- segment_index: 0
source: Our Q3 revenue came in 5% above forecast.
target: Unser Q3-Umsatz lag 5 % unter der Prognose.
errors:
- type: Accuracy
sub_type: Mistranslation
Expand All @@ -4619,6 +4621,8 @@ paths:
- start: 20
end: 29
- segment_index: 1
source: Please share these results with your teams by Friday.
target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team.
errors:
- type: Accuracy
sub_type: Omission
Expand All @@ -4638,15 +4642,6 @@ paths:
target_spans:
- start: 38
end: 48
summary:
overall_score: 72
granular_counts:
Accuracy:
Mistranslation:
Critical: 1
Minor: 1
Omission:
Major: 1
202:
description: Job is still processing. Continue polling after the time suggested by the `Retry-After` header.
headers:
Expand Down Expand Up @@ -8127,6 +8122,13 @@ components:
type: string
description: Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs).
example: de
glossary_ids:
type: array
description: Optional glossary IDs to include when evaluating the segments. Empty values are rejected.
items:
type: string
example:
- "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
segments:
type: array
minItems: 1
Expand Down Expand Up @@ -8157,12 +8159,12 @@ components:
job_id:
type: string
format: uuid
description: The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result.
description: The job identifier. Use it with `GET /v1/quality-evaluations/{job_id}` to poll for the result.
example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
poll_url:
type: string
description: Relative URL you can use to poll for the result.
example: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
example: /v1/quality-evaluations/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19
QualityEvaluationProcessing:
type: object
required:
Expand All @@ -8185,7 +8187,6 @@ components:
- job_id
- status
- segments
- summary
properties:
job_id:
type: string
Expand All @@ -8201,30 +8202,6 @@ components:
description: One entry per submitted segment, in request order.
items:
$ref: '#/components/schemas/QualityEvaluationSegment'
summary:
type: object
required:
- overall_score
- granular_counts
description: Aggregate quality results across all segments.
properties:
overall_score:
type: integer
minimum: 0
maximum: 100
description: Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary).
example: 72
granular_counts:
type: object
description: Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts.
additionalProperties: true
example:
Accuracy:
Mistranslation:
Critical: 1
Minor: 1
Omission:
Major: 1
QualityEvaluationFailed:
title: Error
type: object
Expand Down Expand Up @@ -8266,11 +8243,43 @@ components:
type: integer
description: Zero-based index matching the position of this segment in the request.
example: 0
source:
type: string
description: Source text echoed from the evaluation pipeline. Omitted when empty.
example: Our Q3 revenue came in 5% above forecast.
target:
type: string
description: Target text echoed from the evaluation pipeline. Omitted when empty.
example: Unser Q3-Umsatz lag 5 % unter der Prognose.
entries:
type: array
description: Glossary matches applied to this segment. Omitted when there are no matches.
items:
$ref: '#/components/schemas/QualityEvaluationGlossaryEntry'
errors:
type: array
description: Quality issues identified in this segment. Empty if no issues were found.
items:
$ref: '#/components/schemas/QualityEvaluationIssue'
QualityEvaluationGlossaryEntry:
type: object
required:
- source_entry
- target_entry
properties:
source_entry:
type: string
description: Glossary source term.
example: revenue
target_entry:
type: string
description: Glossary target term.
example: Umsatz
ranges:
type: array
description: Half-open `[start, end)` spans on the segment target text where this match applies.
items:
$ref: '#/components/schemas/QualityEvaluationSpan'
QualityEvaluationIssue:
type: object
required:
Expand Down
Loading