feat(examples): translate one product string with Hy-MT2 1.8B

examples/README.md

@@ -46,6 +46,7 @@ to a separately maintained repository (clone and run there).
 | [Locate every object a prompt can name in a photo](./detect) | Grounding open-vocabulary phrases to boxes on nine photos, with the two boxes it puts on the wrong object kept visible | `extract` | SIE Cloud with Grounding DINO; `fetch.py` pulls the recorded run, `score.py` reproduces the number with no key | Runnable recorded example |
 | [Tag product photos with your own types, colours and materials](./image-classify) | Filling in three catalogue fields from one photo, against AWS Rekognition and four vision LLMs on 938 held-out product photos | `encode` | SIE Cloud with SigLIP so400m; `fetch.py` pulls the recorded run, `score.py` reproduces every figure with no key | Runnable recorded example |
 | [Find a spoken part number in a noisy recording](./speech-to-text) | Transcribing twelve clips and searching them for the doses, figures and statute numbers that matter, the five misses kept | `extract` | SIE Cloud with Whisper large v3 turbo; `fetch.py` pulls the recorded run, `score.py` reproduces the word error rate with no key | Runnable recorded example |
+| [Translate one product string with Hy-MT2 1.8B](./translation) | Translating an Android system message into Japanese with the one generate call behind the translation task page, and checking the output against the recorded one | `generate` | SIE Serverless or a GPU `sie-server` with Hy-MT2 1.8B; the offline tests need no key | Runnable one-call example |
 | [Find the product photo a shopper describes](./image-search) | 309 shopper queries such as "grey leather sofa" over 2,573 Amazon Berkeley Objects product photos, with near misses on colour, material and type; SIE against Voyage, Cohere and GPT captions | `encode` | SigLIP so400m on the SIE server; `fetch.py` pulls the recorded run, `score.py` reproduces every figure with no key | Runnable recorded example |
 | [Find the PDF page that answers a question, without parsing it to text first](./visual-document-search) | 1,816 ViDoRe v3 questions over 16,309 report, filing and slide pages: page images against Voyage, Cohere and parse-then-embed | `encode` | SIE `tomoro-colqwen3-embed-4b:compact`; `fetch.py` pulls the recorded run, `score.py` recomputes every score with no key | Runnable recorded example |
 | [Search licensed images with text](./multimodal-search) | Recomputing a six-image hard-negative ranking from full SigLIP vectors | `encode` | SIE endpoint with SigLIP; standalone `uv` project | Runnable verified example |

examples/translation/.gitignore

@@ -0,0 +1,2 @@
+.venv/
+__pycache__/

examples/translation/README.md

@@ -0,0 +1,157 @@
+# Translate one product string with Hy-MT2 1.8B
+
+One English string from Android, translated into Japanese with one call to
+`tencent/Hy-MT2-1.8B` on SIE. It is the call behind
+[superlinked.com/translation](https://superlinked.com/translation), whose
+sources are in its
+[SOURCES.md](https://superlinked.com/reference/translation/SOURCES.md).
+
+The string is Android's notification-permission message:
+
+> Starting in Android 13, apps that you install need your permission to send
+> notifications. Tap to change this permission for existing apps.
+
+Recorded through SIE Serverless (`https://api.superlinked.com`) on 2026-10-25,
+Hy-MT2 returned:
+
+> Android 13以降では、インストールしたアプリが通知を送信するにはあなたの許可が必要です。既存のアプリのこの許可を変更するにはタップしてください。
+
+It finished with `stop` after 50 input and 51 output tokens. The version
+number comes through as "Android 13以降"; Android's own Japanese writes
+"Android 13 以降". Where Android's Japanese says 権限, its word for an app
+permission, Hy-MT2 writes 許可, the everyday word for permission.
+
+## The call
+
+```text
+POST https://api.superlinked.com/v1/generate/tencent__Hy-MT2-1.8B
+{"prompt": "<｜hy_begin▁of▁sentence｜><｜hy_User｜>Translate the following text into Japanese. Note that you should only output the translated result without any additional explanation: Starting in Android 13, apps that you install need your permission to send notifications. Tap to change this permission for existing apps.<｜hy_Assistant｜>",
+ "max_new_tokens": 256,
+ "temperature": 0}
+```
+
+With the Python SDK, as `run.py` sends it:
+
+```python
+from sie_sdk import SIEClient
+
+with SIEClient() as client:  # SIE_API_KEY for Serverless, or SIE_BASE_URL for your own server
+    result = client.generate("tencent/Hy-MT2-1.8B", prompt, max_new_tokens=256, temperature=0)
+print(result["text"])
+```
+
+`/v1/generate` takes a raw prompt and applies no chat template, so the prompt
+carries Hy-MT2's own turn markers around the English instruction from its
+[model card](https://huggingface.co/tencent/Hy-MT2-1.8B/blob/9a341cd1b679d3efd23b46e847b01745a71ed792/README.md).
+Name the target language in English. The card puts a blank line between the
+instruction and the text; the recorded call used one space, and `run.py`
+builds the prompt the same way. The call sets temperature 0 because the model
+profile defaults to 0.7.
+
+## Run it
+
+From this directory:
+
+```sh
+uv sync --frozen
+uv run --frozen python run.py --show
+SIE_API_KEY=sk-sie-... uv run --frozen python run.py
+```
+
+`--show` prints the request and sends nothing, so it needs no key. The live run
+sends one generate call and prints the translation, its finish reason, its
+token counts and whether the text equals the recorded one:
+
+```json
+{
+  "model": "tencent/Hy-MT2-1.8B",
+  "text": "Android 13以降では、インストールしたアプリが通知を送信するにはあなたの許可が必要です。既存のアプリのこの許可を変更するにはタップしてください。",
+  "finish_reason": "stop",
+  "usage": {
+    "prompt_tokens": 50,
+    "completion_tokens": 51
+  },
+  "matches_recorded": true,
+  "recorded_on": "2026-10-25"
+}
+```
+
+That is the output of a run on 2026-10-28. Your text can differ: SIE's output
+is not deterministic even at temperature 0. In the study below, pairs of
+identical requests got different outputs 21% to 25% of the time. A `false` in
+`matches_recorded` is not an error.
+
+To translate something else, pass `--text` and `--into`, the target language
+named in English:
+
+```sh
+uv run --frozen python run.py --text "Your order has shipped." --into German
+```
+
+The comparison with the recording is then left out. `run.py` sizes
+`max_new_tokens` from the input the way the page does: 5 tokens per 3
+characters plus 16, rounded up to 64, 128, 256, 512 or 1024. The recorded
+string gets 256, and text over about 300 characters gets the model's maximum
+of 1024. If a translation still reaches its cap, the finish reason is `length`
+and the text is cut off: `run.py` prints the output, warns on stderr and exits
+with status 1. Split longer text into parts.
+
+The first call after the model has been idle can wait a few minutes while
+capacity starts. The SDK waits through the responses that come before
+generation starts (`429`, and `503` while capacity starts or the model loads),
+for up to five minutes here. It does not send the call again after a gateway
+timeout or a dropped connection, when the generation may already have run.
+
+The full response also carries request ids, timings and billing fields; the
+example prints none of them. On a failure it prints only the error type and the
+HTTP status, because SDK error text can carry request context. The key is read
+from `SIE_API_KEY` and never printed.
+
+### On your own server
+
+Hy-MT2 runs on the GPU generation image:
+
+```sh
+docker run --gpus all -p 8080:8080 \
+  -v sie-hf-cache:/app/.cache/huggingface \
+  ghcr.io/superlinked/sie-server:latest-cuda12-sglang
+SIE_BASE_URL=http://localhost:8080 uv run --frozen python run.py
+```
+
+SIE's [model config](../../packages/sie_server/models/tencent__Hy-MT2-1.8B.yaml)
+pins Hugging Face revision `9a341cd1b679d3efd23b46e847b01745a71ed792` and
+serves it with SGLang in bfloat16. SIE Serverless also serves
+`google/madlad400-3b-mt`, which takes the source after a target tag such as
+`<2ja> ` instead of an instruction; this example does not call it.
+
+## How well it translates
+
+The page's figures come from a WMT24++ study. Its sample,
+every published output, both score files, the scorer and a script that
+recomputes the scores are public:
+[superlinked/sie-task-evidence @c4add1e0, translation/wmt24pp-study-2026-10](https://huggingface.co/datasets/superlinked/sie-task-evidence/tree/c4add1e09ebffc5f0d0909b88b9671597de0bebc/translation/wmt24pp-study-2026-10).
+
+## Test without a key
+
+```sh
+uv run --frozen python -m unittest discover -s tests -v
+uv run --frozen ruff check .
+uv run --frozen ruff format --check .
+```
+
+The tests run the real SDK against an HTTPX `MockTransport`. They check that it
+sends one POST to `/v1/generate/tencent__Hy-MT2-1.8B` whose JSON equals the
+recorded body, sizes the output cap from the input as the page does, sends the
+key as a bearer token, prints no error detail, flags a cut-off translation and
+does not resend after a gateway timeout. They compare the parsed JSON, not the
+bytes: the SDK escapes non-ASCII characters, and the recorded call was sent as
+UTF-8. No model runs and nothing leaves the machine.
+
+## Source
+
+The English string is `review_notification_settings_text` from
+[`core/res/res/values/strings.xml`](https://android.googlesource.com/platform/frameworks/base/+/refs/tags/android-15.0.0_r1/core/res/res/values/strings.xml)
+in the Android Open Source Project's `frameworks/base`, tag
+`android-15.0.0_r1`, under the Apache License 2.0. [recorded.json](recorded.json)
+holds the string, the recorded request and the response fields this example
+prints.

examples/translation/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "superlinked-sie-translation-example"
+version = "0.1.0"
+description = "Translate one product string into Japanese with Hy-MT2 1.8B on SIE"
+requires-python = ">=3.12,<3.13"
+dependencies = ["sie-sdk==0.10.1"]
+
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = ["ruff==0.14.14"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"

examples/translation/recorded.json

@@ -0,0 +1,34 @@
+{
+  "source": {
+    "text": "Starting in Android 13, apps that you install need your permission to send notifications. Tap to change this permission for existing apps.",
+    "language": "English",
+    "translate_into": "Japanese",
+    "locale": "ja_JP",
+    "origin": "The Android Open Source Project, frameworks/base, core/res/res/values/strings.xml, string review_notification_settings_text, tag android-15.0.0_r1",
+    "url": "https://android.googlesource.com/platform/frameworks/base/+/refs/tags/android-15.0.0_r1/core/res/res/values/strings.xml",
+    "licence": "Apache-2.0"
+  },
+  "recorded": {
+    "date": "2026-10-25",
+    "endpoint": "https://api.superlinked.com",
+    "request": {
+      "method": "POST",
+      "path": "/v1/generate/tencent__Hy-MT2-1.8B",
+      "body": {
+        "prompt": "<｜hy_begin▁of▁sentence｜><｜hy_User｜>Translate the following text into Japanese. Note that you should only output the translated result without any additional explanation: Starting in Android 13, apps that you install need your permission to send notifications. Tap to change this permission for existing apps.<｜hy_Assistant｜>",
+        "max_new_tokens": 256,
+        "temperature": 0
+      }
+    },
+    "response": {
+      "model": "tencent/Hy-MT2-1.8B",
+      "text": "Android 13以降では、インストールしたアプリが通知を送信するにはあなたの許可が必要です。既存のアプリのこの許可を変更するにはタップしてください。",
+      "finish_reason": "stop",
+      "usage": {
+        "prompt_tokens": 50,
+        "completion_tokens": 51,
+        "total_tokens": 101
+      }
+    }
+  }
+}

examples/translation/run.py

@@ -0,0 +1,144 @@
+"""Translate one product string into Japanese with tencent/Hy-MT2-1.8B on SIE.
+
+    uv run --frozen python run.py --show   # print the request, send nothing
+    uv run --frozen python run.py          # send it (needs SIE_API_KEY or SIE_BASE_URL)
+
+One native generate call, the call https://superlinked.com/translation shows:
+
+    POST /v1/generate/tencent__Hy-MT2-1.8B
+    {"prompt": "<Hy-MT2 turn markers, instruction naming Japanese, source text>",
+     "max_new_tokens": 256, "temperature": 0}
+
+max_new_tokens grows with the input the way the page sizes it: 256 for the
+recorded string, up to the model's 1024 for longer text. A translation that
+stops at that cap (finish reason "length") is cut off, so the run exits 1.
+
+The key comes from SIE_API_KEY and is never printed. Without SIE_BASE_URL the
+SDK sends the call to SIE Serverless, https://api.superlinked.com.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from sie_sdk import SIEClient
+
+HERE = Path(__file__).resolve().parent
+RECORDED = json.loads((HERE / "recorded.json").read_text(encoding="utf-8"))
+
+MODEL = "tencent/Hy-MT2-1.8B"
+# Native generate takes the SIE-safe id; the SDK normalizes it.
+PATH = f"/v1/generate/{MODEL.replace('/', '__')}"
+SERVERLESS = "https://api.superlinked.com"
+# The output cap, as the page computes it: 5 output tokens per 3 input
+# characters plus 16, rounded up to the next bucket, never above the model's
+# declared 1024.
+OUTPUT_TOKEN_BUCKETS = (64, 128, 256, 512, 1024)
+OUTPUT_EXPANSION = 5
+MAX_OUTPUT_TOKENS = 1024
+# The model profile defaults to temperature 0.7, so the call asks for 0.
+TEMPERATURE = 0
+# The raw prompt for /v1/generate: Hy-MT2's chat turn markers around the
+# English instruction from its model card. The recorded call puts one space
+# between the instruction and the text, where the card puts a blank line.
+PROMPT = (
+    "<｜hy_begin▁of▁sentence｜><｜hy_User｜>Translate the following text into {language}. "
+    "Note that you should only output the translated result without any additional explanation: "
+    "{text}<｜hy_Assistant｜>"
+)
+
+
+def build_prompt(text: str, language: str) -> str:
+    """Hy-MT2's prompt for one source text, edge whitespace removed."""
+    return PROMPT.format(language=language, text=text.strip())
+
+
+def output_cap(text: str) -> int:
+    """max_new_tokens for one source text; len() counts code points, as the page does."""
+    raw = OUTPUT_EXPANSION * math.ceil(len(text.strip()) / 3) + 16
+    bucket = next((size for size in OUTPUT_TOKEN_BUCKETS if size >= raw), OUTPUT_TOKEN_BUCKETS[-1])
+    return min(bucket, MAX_OUTPUT_TOKENS)
+
+
+def request_body(text: str, language: str) -> dict[str, Any]:
+    return {"prompt": build_prompt(text, language), "max_new_tokens": output_cap(text), "temperature": TEMPERATURE}
+
+
+def translate(client: SIEClient, text: str, language: str) -> dict[str, Any]:
+    """Send one generate call and keep the fields a caller reads."""
+    result = client.generate(
+        MODEL,
+        build_prompt(text, language),
+        max_new_tokens=output_cap(text),
+        temperature=TEMPERATURE,
+        provision_timeout_s=300,
+    )
+    if not isinstance(result.get("text"), str):
+        raise ValueError("The response has no text")
+    usage = result.get("usage") or {}
+    # The full response also carries request ids, timings and billing fields;
+    # only the translation and its token counts are printed.
+    return {
+        "model": result.get("model"),
+        "text": result["text"],
+        "finish_reason": result.get("finish_reason"),
+        "usage": {key: usage.get(key) for key in ("prompt_tokens", "completion_tokens")},
+    }
+
+
+def is_recorded_case(text: str, language: str) -> bool:
+    source = RECORDED["source"]
+    return text.strip() == source["text"] and language == source["translate_into"]
+
+
+def main(argv: list[str] | None = None) -> int:
+    source = RECORDED["source"]
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--show", action="store_true", help="print the request and exit, sending nothing")
+    parser.add_argument("--text", default=source["text"], help="English text to translate (default: the recorded one)")
+    parser.add_argument(
+        "--into", default=source["translate_into"], help="target language name, in English (default: Japanese)"
+    )
+    args = parser.parse_args(argv)
+    if not args.text.strip():
+        parser.error("--text is empty")
+
+    base_url = os.environ.get("SIE_BASE_URL", "").strip()
+    if args.show:
+        request = {"method": "POST", "url": (base_url or SERVERLESS).rstrip("/") + PATH}
+        print(json.dumps({**request, "body": request_body(args.text, args.into)}, ensure_ascii=False, indent=2))
+        return 0
+    if not base_url and not os.environ.get("SIE_API_KEY", "").strip():
+        parser.error("set SIE_API_KEY for SIE Serverless, or SIE_BASE_URL for your own server")
+
+    try:
+        with SIEClient(timeout_s=150) as client:
+            output = translate(client, args.text, args.into)
+    except Exception as exc:  # noqa: BLE001 - SDK error text can carry request context; print only its kind.
+        status = getattr(exc, "status_code", None)
+        detail = f"{type(exc).__name__}" + (f", HTTP {status}" if status else "")
+        print(f"The translation call failed ({detail}).", file=sys.stderr)
+        return 1
+
+    if is_recorded_case(args.text, args.into):
+        recorded = RECORDED["recorded"]
+        output["matches_recorded"] = output["text"] == recorded["response"]["text"]
+        output["recorded_on"] = recorded["date"]
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+    if output["finish_reason"] == "length":
+        print(
+            f"The translation was cut off at the {output_cap(args.text)}-token output cap (finish reason length).",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())