From 56d5007be9987e70eb12f7fc0fa2e8292b6fb743 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 8 Sep 2026 16:48:00 +0200 Subject: [PATCH] site: OpenAPI matches production; About gains the results section The OpenAPI document advertised the retired server URL (interscript.org/api) and documented a GET form the live API does not implement. Now: server https://api.interscript.org/v1, POST-only /transliterate, and the missing /infer (neural models) and /info endpoints - every path verified against production before documenting. About gains a 'What the measurements show' section in plain user language: the benchmark outcome for our Arabic model, the frontier- model comparison (including the one figure we could not reproduce, stated as such), the browser-size model, and a link to the full tables on /ml. --- src/pages/about.astro | 19 ++++++ src/pages/openapi.json.ts | 135 +++++++++++++++++++++----------------- 2 files changed, 94 insertions(+), 60 deletions(-) diff --git a/src/pages/about.astro b/src/pages/about.astro index 008860c..4faf659 100644 --- a/src/pages/about.astro +++ b/src/pages/about.astro @@ -123,6 +123,25 @@ const partners: Partner[] = [

+
+

What the measurements show

+

+ For conversions no authority document covers — restoring the diacritics a scribe left out, + or reading unwritten Thai as phonemes — we train neural models and measure them the same + way we test maps. On the public Arabic benchmark SadeedDiac-25, our Arabic model scores + 2.29% error with 580 million parameters: better than every general-purpose language model + we measured it against (one vendor-published figure is lower; we could not reproduce it), + and about three times better than the 1.5-billion-parameter system the benchmark was + published with. The newest general-purpose models we tested were three to five times + worse than their predecessor on this task. One of our models is small enough (95 MB) to + run in a web browser. +

+

+ Every score, the method used to produce it, and the full results table are on + the neural layer page. +

+
+

History

diff --git a/src/pages/openapi.json.ts b/src/pages/openapi.json.ts index fc472a2..34dec39 100644 --- a/src/pages/openapi.json.ts +++ b/src/pages/openapi.json.ts @@ -32,77 +32,20 @@ const spec = { url: "https://opensource.org/license/bsd-2-clause", }, }, - servers: [{ url: `${SITE}/api` }], + servers: [{ url: "https://api.interscript.org/v1" }], tags: [ { name: "transliterate", description: "Run a transliteration system" }, { name: "systems", description: "Browse the system catalogue" }, { name: "detect", description: "Find a matching system" }, + { name: "infer", description: "Run a neural model" }, ], paths: { "/transliterate": { - get: { - tags: ["transliterate"], - summary: "Transliterate a single string", - description: - "Translates non-Latin text into Latin (or another script) using the named authority system. Idempotent, cacheable for the lifetime of a system version.", - operationId: "transliterateGet", - parameters: [ - { - name: "system", - in: "query", - required: true, - description: "Interscript system code (e.g. `bgnpcgn-ukr-Cyrl-Latn-2019`).", - schema: { type: "string", maxLength: 200 }, - example: "bgnpcgn-ukr-Cyrl-Latn-2019", - }, - { - name: "input", - in: "query", - required: true, - description: "Source text to transliterate.", - schema: { type: "string", maxLength: 10_000 }, - example: "Антон", - }, - { - name: "stage", - in: "query", - required: false, - description: "Stage to execute (default: `main`).", - schema: { type: "string", default: "main" }, - }, - ], - responses: { - "200": { - description: "Successful transliteration.", - content: { - "application/json": { - schema: { $ref: "#/components/schemas/TransliterationResult" }, - }, - }, - }, - "400": { - description: "Missing or invalid parameters.", - content: { - "application/json": { - schema: { $ref: "#/components/schemas/Error" }, - }, - }, - }, - "404": { - description: "System not found.", - content: { - "application/json": { - schema: { $ref: "#/components/schemas/Error" }, - }, - }, - }, - }, - }, post: { tags: ["transliterate"], summary: "Transliterate via JSON body", description: - "Same as GET /transliterate but accepts a JSON body — useful when input is large, contains newlines, or you prefer POST semantics.", + "Accepts a JSON body. The only request form this endpoint supports — query-parameter GET requests are not implemented.", operationId: "transliteratePost", requestBody: { required: true, @@ -233,6 +176,78 @@ const spec = { }, }, }, + "/infer": { + post: { + tags: ["infer"], + summary: "Run a neural model", + description: + "Runs a neural model from the model index (diacritization, grapheme-to-phoneme). Model ids and their measured scores are listed in the models.yaml index; see interscript.org/ml for the catalogue.", + operationId: "inferPost", + requestBody: { + required: true, + content: { + "application/json": { + schema: { + type: "object", + required: ["model", "input"], + properties: { + model: { type: "string", example: "ara-diac-small-2.1" }, + input: { type: "string", example: "كتاب" }, + }, + }, + }, + }, + }, + responses: { + "200": { + description: "Successful inference.", + content: { + "application/json": { + schema: { + type: "object", + properties: { + model: { type: "string" }, + task: { type: "string" }, + input: { type: "string" }, + output: { type: "string", example: "كِتَابٍ" }, + }, + }, + }, + }, + }, + }, + }, + options: { + tags: ["infer"], + summary: "CORS preflight", + responses: { "204": { description: "No content" } }, + }, + }, + "/info": { + get: { + tags: ["systems"], + summary: "API version and catalogue counts", + description: "Returns the API version, the map count, and the model count.", + operationId: "infoGet", + responses: { + "200": { + description: "API metadata.", + content: { + "application/json": { + schema: { + type: "object", + properties: { + api_version: { type: "string" }, + maps: { type: "integer" }, + models: { type: "integer" }, + }, + }, + }, + }, + }, + }, + }, + }, "/detect": { get: { tags: ["detect"],