jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/providers/cloudflare.py

@@ -0,0 +1,59 @@
+"""Cloudflare Workers AI (`provider.ts:230-260`): the Jev contract inside `{model, input}` and the v4 envelope."""
+
+from typing import ClassVar
+
+import httpx
+
+from jev_mcp.domain import JsonValue, is_json_object
+from jev_mcp.errors import Redactor
+from jev_mcp.providers.base import Evaluation, HttpProvider, ProviderName, decode_body, parse_envelope
+from jev_mcp.serialize import stringify_compact
+
+
+def cloudflare_slug(model: str) -> str:
+    """A `typesafe/` model is kept verbatim; `jev-latest` is the single alias `typesafe/jev`."""
+    if model.startswith("typesafe/"):
+        return model
+    return f"typesafe/{'jev' if model == 'jev-latest' else model}"
+
+
+class CloudflareProvider(HttpProvider):
+    name: ClassVar[ProviderName] = "cloudflare"
+    label: ClassVar[str] = "Cloudflare AI run"
+
+    def __init__(
+        self, redact: Redactor, *, api_token: str, account_id: str, client: httpx.AsyncClient | None = None
+    ) -> None:
+        super().__init__(redact, client)
+        self._api_token = api_token
+        self._url = f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run"
+
+    async def _send(
+        self, state: JsonValue, questions: dict[str, JsonValue], model: str, timeout: float | None
+    ) -> Evaluation:
+        slug = cloudflare_slug(model)
+        response = await self._post(
+            self._url,
+            {"Authorization": f"Bearer {self._api_token}"},
+            {"model": slug, "input": {"state": state, "questions": questions}},
+        )
+        # `.json().catch(() => ({}))`: an unparseable body is an empty object here, not null.
+        parsed = decode_body(response.content)
+        body: object = {} if parsed is None else parsed
+        record: dict[str, object] = body if is_json_object(body) else {}
+        errors = record.get("errors")
+        if not response.is_success or record.get("success") is False:
+            raise self._status_error(response.status_code, stringify_compact(body if errors is None else errors))
+        # The v4 envelope double-nests: `result.result` holds the model output.
+        outer = record.get("result")
+        inner: object = None
+        if is_json_object(outer):
+            run_state = outer.get("state")
+            # A missing state is not an error; only a string other than Completed is.
+            if isinstance(run_state, str) and run_state != "Completed":
+                raise self._status_error(f"state {run_state}", stringify_compact([] if errors is None else errors))
+            inner = outer.get("result")
+        payload = inner if inner is not None else outer if outer is not None else body
+        # ADR-0003: the unwrapped payload gets the uniform envelope rules; the reference used `answers ?? {}`.
+        envelope = parse_envelope(payload, self.label)
+        return Evaluation(envelope.answers, envelope.usage, self.name, envelope.model_or(slug))

jev_mcp/providers/compatible.py

@@ -0,0 +1,43 @@
+"""A caller-configured Jev-compatible System One endpoint (`provider.ts:158-201`)."""
+
+from typing import ClassVar
+
+import httpx
+
+from jev_mcp.domain import JsonValue
+from jev_mcp.errors import Redactor
+from jev_mcp.providers.base import (
+    Evaluation,
+    HttpProvider,
+    ProviderName,
+    decode_body,
+    decode_text,
+    parse_envelope,
+    refuse_credentials_in_url,
+)
+
+
+class CompatibleProvider(HttpProvider):
+    name: ClassVar[ProviderName] = "compatible"
+    label: ClassVar[str] = "Jev-compatible endpoint"
+
+    def __init__(
+        self, redact: Redactor, *, api_key: str, base_url: str, client: httpx.AsyncClient | None = None
+    ) -> None:
+        super().__init__(redact, client)
+        self._api_key = api_key
+        self._base_url = base_url
+
+    async def _send(
+        self, state: JsonValue, questions: dict[str, JsonValue], model: str, timeout: float | None
+    ) -> Evaluation:
+        refuse_credentials_in_url(self._base_url, self.label)
+        response = await self._post(
+            self._base_url,
+            {"Authorization": f"Bearer {self._api_key}"},
+            {"model": model, "state": state, "questions": questions},
+        )
+        if not response.is_success:
+            raise self._status_error(response.status_code, decode_text(response.content))
+        envelope = parse_envelope(decode_body(response.content), self.label)
+        return Evaluation(envelope.answers, envelope.usage, self.name, envelope.model_or(model))

jev_mcp/providers/openrouter.py

@@ -0,0 +1,47 @@
+"""OpenRouter's Decisions API (`provider.ts:126-156`)."""
+
+from typing import ClassVar
+
+import httpx
+
+from jev_mcp.domain import JsonValue
+from jev_mcp.errors import Redactor
+from jev_mcp.providers.base import Evaluation, HttpProvider, ProviderName, decode_body, decode_text, parse_envelope
+
+URL = "https://openrouter.ai/api/alpha/decisions"
+LATEST = "jev-1.13"
+"""OpenRouter has no redirecting `jev-latest` slug; the reference maps it to this release."""
+_TITLE = "jev-mcp"
+_REFERER = "https://github.com/PyModel/jev-mcp"
+
+
+def openrouter_slug(model: str) -> str:
+    """`jev-latest` becomes `jev-1.13` first; then `typesafe/` is prefixed unless already there."""
+    effective = LATEST if model == "jev-latest" else model
+    return effective if effective.startswith("typesafe/") else f"typesafe/{effective}"
+
+
+class OpenRouterProvider(HttpProvider):
+    name: ClassVar[ProviderName] = "openrouter"
+    label: ClassVar[str] = "OpenRouter decisions API"
+
+    def __init__(self, redact: Redactor, *, api_key: str, client: httpx.AsyncClient | None = None) -> None:
+        super().__init__(redact, client)
+        self._api_key = api_key
+
+    async def _send(
+        self, state: JsonValue, questions: dict[str, JsonValue], model: str, timeout: float | None
+    ) -> Evaluation:
+        slug = openrouter_slug(model)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "HTTP-Referer": _REFERER,
+            "X-Title": _TITLE,
+            "X-OpenRouter-Title": _TITLE,
+        }
+        response = await self._post(URL, headers, {"model": slug, "state": state, "questions": questions})
+        if not response.is_success:
+            raise self._status_error(response.status_code, decode_text(response.content))
+        envelope = parse_envelope(decode_body(response.content), self.label)
+        # The reference reports the slug it sent, never a model from the body (`provider.ts:154`).
+        return Evaluation(envelope.answers, envelope.usage, self.name, slug)

jev_mcp/providers/resolver.py

@@ -0,0 +1,106 @@
+"""Provider resolution from process configuration (`provider.ts:35-77`, ADR-0007, ADR-0008).
+
+Explicit `JEV_PROVIDER` (lowercased) wins; an unknown name falls through to auto resolution in the
+reference order typesafe, openrouter, cloudflare, vercel, compatible. A variable set to the empty
+string counts as unset, as it is falsy in JS. Vercel keeps its slot but is unsupported (ADR-0007).
+Resolution raises `ProviderConfigError` before any request, so the tools report it per call.
+"""
+
+from pydantic import SecretStr
+
+from jev_mcp.errors import Redactor
+from jev_mcp.providers.base import JevProvider, ProviderConfigError
+from jev_mcp.providers.cloudflare import CloudflareProvider
+from jev_mcp.providers.compatible import CompatibleProvider
+from jev_mcp.providers.openrouter import OpenRouterProvider
+from jev_mcp.providers.typesafe import TypeSafeProvider
+from jev_mcp.settings import Settings
+
+DEFAULT_MODEL = "jev-latest"
+
+VERCEL_UNSUPPORTED = (
+    "vercel provider is not supported by the Python server; use typesafe, openrouter, cloudflare or compatible"
+)
+NO_CREDENTIALS = (
+    "No Jev provider credentials found. Set TYPESAFE_API_KEY, OPENROUTER_API_KEY (sk-or-), Cloudflare token + "
+    "CLOUDFLARE_ACCOUNT_ID, AI_GATEWAY_API_KEY, or JEV_API_KEY + JEV_API_BASE_URL; set JEV_PROVIDER to choose "
+    "explicitly."
+)
+
+
+def resolve_model(settings: Settings) -> str:
+    """`process.env.JEV_MCP_MODEL ?? "jev-latest"` (`index.ts:72`): an empty model stays empty."""
+    return DEFAULT_MODEL if settings.jev_mcp_model is None else settings.jev_mcp_model
+
+
+def resolve_provider(settings: Settings) -> JevProvider:
+    """The provider `settings` select, or `ProviderConfigError` with the reference's text."""
+    redact = Redactor(settings.secret_values())
+    explicit = settings.jev_provider.lower()
+    typesafe_key = _value(settings.typesafe_api_key)
+    openrouter_key = _value(settings.openrouter_api_key)
+    has_openrouter = openrouter_key.startswith("sk-or-")
+    cloudflare_token = _value(settings.jev_cloudflare_api_token) or _value(settings.cloudflare_api_token)
+    account_id = settings.cloudflare_account_id or ""
+    has_cloudflare = bool(cloudflare_token and account_id)
+    api_key = _value(settings.jev_api_key)
+    base_url = _value(settings.jev_api_base_url)
+
+    def typesafe() -> JevProvider:
+        return TypeSafeProvider(redact, api_key=typesafe_key, base_url=_value(settings.typesafe_base_url) or None)
+
+    def openrouter() -> JevProvider:
+        return OpenRouterProvider(redact, api_key=openrouter_key)
+
+    def cloudflare() -> JevProvider:
+        return CloudflareProvider(redact, api_token=cloudflare_token, account_id=account_id)
+
+    def compatible() -> JevProvider:
+        return CompatibleProvider(redact, api_key=api_key, base_url=base_url)
+
+    match explicit:
+        case "typesafe":
+            if not typesafe_key:
+                raise ProviderConfigError("JEV_PROVIDER=typesafe but TYPESAFE_API_KEY is not set.")
+            return typesafe()
+        case "openrouter":
+            if not has_openrouter:
+                raise ProviderConfigError(
+                    "JEV_PROVIDER=openrouter but OPENROUTER_API_KEY is not set or not an sk-or- key."
+                )
+            return openrouter()
+        case "vercel":
+            raise ProviderConfigError(VERCEL_UNSUPPORTED)
+        case "cloudflare":
+            if not has_cloudflare:
+                raise ProviderConfigError(
+                    "JEV_PROVIDER=cloudflare but a Cloudflare API token (CLOUDFLARE_API_TOKEN or "
+                    "JEV_CLOUDFLARE_API_TOKEN) and CLOUDFLARE_ACCOUNT_ID are not both set."
+                )
+            return cloudflare()
+        case "compatible":
+            missing = [name for name, value in (("JEV_API_KEY", api_key), ("JEV_API_BASE_URL", base_url)) if not value]
+            if missing:
+                verb = "are" if len(missing) > 1 else "is"
+                raise ProviderConfigError(
+                    f"JEV_PROVIDER=compatible but {' and '.join(missing)} {verb} not set. "
+                    "JEV_MCP_MODEL is optional and defaults to jev-latest."
+                )
+            return compatible()
+        case _:
+            pass
+    if typesafe_key:
+        return typesafe()
+    if has_openrouter:
+        return openrouter()
+    if has_cloudflare:
+        return cloudflare()
+    if _value(settings.ai_gateway_api_key):
+        raise ProviderConfigError(VERCEL_UNSUPPORTED)
+    if api_key and base_url:
+        return compatible()
+    raise ProviderConfigError(NO_CREDENTIALS)
+
+
+def _value(secret: SecretStr | None) -> str:
+    return "" if secret is None else secret.get_secret_value()

jev_mcp/providers/typesafe.py

@@ -0,0 +1,127 @@
+"""TypeSafe direct through `typesafe-sdk` (`provider.ts:108-124`), the optional `typesafe` extra.
+
+The SDK is imported on first use, so the server runs without it when another provider is configured.
+It keeps its default retry policy, as the reference keeps `@typesafe-ai/sdk`'s. Its typed response
+model is bypassed: the raw body goes through the uniform envelope rules (ADR-0003) and answers stay
+raw for the tools to validate.
+"""
+
+from typing import TYPE_CHECKING, Any, ClassVar, Self, cast, override
+
+from pydantic import RootModel
+
+from jev_mcp.domain import JsonValue
+from jev_mcp.errors import Redactor
+from jev_mcp.providers.base import (
+    Evaluation,
+    JevProvider,
+    ProviderError,
+    ProviderName,
+    decode_body,
+    parse_envelope,
+    refuse_credentials_in_url,
+)
+from jev_mcp.serialize import stringify_compact
+
+if TYPE_CHECKING:
+    import httpx2
+    from typesafe_sdk import AsyncTypeSafeClient, RetryPolicy
+
+
+class _RawBody(RootModel[object]):
+    """The response body as `JSON.parse` would read it: `None` when it is not JSON, NaN never a number."""
+
+    @override
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        extra: Any = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        content = json_data.encode() if isinstance(json_data, str) else bytes(json_data)
+        return cls.model_construct(decode_body(content))
+
+
+class TypeSafeProvider(JevProvider):
+    name: ClassVar[ProviderName] = "typesafe"
+    label: ClassVar[str] = "TypeSafe API"
+
+    def __init__(
+        self,
+        redact: Redactor,
+        *,
+        api_key: str,
+        base_url: str | None,
+        transport: "httpx2.AsyncBaseTransport | None" = None,
+        retry: "RetryPolicy | None" = None,
+    ) -> None:
+        super().__init__(redact)
+        self._api_key = api_key
+        self._base_url = base_url
+        self._transport = transport
+        self._retry = retry
+        self._client: AsyncTypeSafeClient | None = None
+
+    def _sdk_client(self) -> "AsyncTypeSafeClient":
+        if self._client is None:
+            try:
+                from typesafe_sdk import AsyncTypeSafeClient
+            except ImportError:
+                raise ProviderError(
+                    "The typesafe provider needs the typesafe-sdk package: install jev-mcp-python[typesafe]."
+                ) from None
+            self._client = AsyncTypeSafeClient(
+                api_key=self._api_key, base_url=self._base_url, transport=self._transport, retry=self._retry
+            )
+        return self._client
+
+    async def _send(
+        self, state: JsonValue, questions: dict[str, JsonValue], model: str, timeout: float | None
+    ) -> Evaluation:
+        if self._base_url is not None:
+            refuse_credentials_in_url(self._base_url, self.label)
+        client = self._sdk_client()
+        import httpx2
+        from typesafe_sdk import TypeSafeAPIConnectionError, TypeSafeAPIError
+
+        try:
+            # The SDK's recursive JSON alias is partly unknown to pyright and narrower than JsonValue;
+            # the wire is the same.
+            response = await client.system_one(  # pyright: ignore[reportUnknownMemberType]
+                cast(Any, state),
+                cast(Any, questions),
+                model=model,
+                # `None` must wait, as fetch does: the SDK reads a bare `None` as its 10 s default.
+                timeout=httpx2.Timeout(None) if timeout is None else timeout,
+                response_model=_RawBody,
+            )
+        except TypeSafeAPIError as error:
+            raise self._status_error(error.status, _body_text(error.body)) from None
+        except TypeSafeAPIConnectionError as error:
+            # The SDK writes `Connection error: {cause}`; a reset's cause has an empty message.
+            cause = error.__cause__
+            if isinstance(error, TimeoutError) or cause is None or str(cause):
+                raise
+            raise ProviderError(f"{self.label} request failed: {error}{type(cause).__name__}") from None
+        envelope = parse_envelope(response.root, self.label)
+        # The reference reports the requested model, never one from the body (`provider.ts:122`).
+        return Evaluation(envelope.answers, envelope.usage, self.name, model)
+
+    @override
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+
+
+def _body_text(body: object) -> str:
+    """The SDK hands over the error body parsed: text as text, JSON re-serialized, nothing as nothing."""
+    if body is None:
+        return ""
+    if isinstance(body, str):
+        return body
+    return stringify_compact(body)

jev_mcp/serialize.py

@@ -0,0 +1,199 @@
+"""JS-compatible `JSON.stringify(payload, null, 2)` and `Number.prototype.toFixed` (ADR-0006).
+
+Numbers follow ECMAScript Number::toString: shortest round-trip digits, integral values without a
+fraction, exponential form only when the decimal exponent is >= 21 or <= -7. Object keys follow JS
+own-property order: array-index keys ascending first, then the rest in insertion order.
+`js_number_to_locale_string_en_us` (ADR-0014) renders cap-sized integers the way the reference's
+error text does.
+"""
+
+import math
+import re
+from collections.abc import Iterable, Mapping
+from decimal import ROUND_HALF_UP, Context, Decimal
+from typing import Final, final
+
+
+@final
+class _Undefined:
+    """JS `undefined`: an object key holding it is omitted, an array slot holding it prints `null`."""
+
+    def __repr__(self) -> str:
+        return "UNDEFINED"
+
+
+UNDEFINED: Final = _Undefined()
+
+_MAX_ARRAY_INDEX = 2**32 - 2
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+_NEEDS_ESCAPE = re.compile('[\ud800-\udbff][\udc00-\udfff]|["\\\\\x00-\x1f\ud800-\udfff]')
+_DECIMAL_CONTEXT = Context(prec=400)
+
+
+def stringify(value: object) -> str:
+    """`JSON.stringify(value, null, 2)` for parsed-JSON-shaped values (dict, list, tuple, str, number, bool, None).
+
+    NaN and infinities print `null`, `-0.0` prints `0`, integers print as the float64 JS would hold.
+    """
+    if value is UNDEFINED:
+        raise TypeError("JSON.stringify(undefined) produces no text.")
+    return _stringify(value, "")
+
+
+def stringify_compact(value: object) -> str:
+    """`JSON.stringify(value)` with no indentation, for parsed-JSON-shaped values (provider error text)."""
+    if value is UNDEFINED:
+        raise TypeError("JSON.stringify(undefined) produces no text.")
+    return _stringify(value, None)
+
+
+def _stringify(value: object, indent: str | None) -> str:
+    if value is None or value is UNDEFINED:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int | float):
+        number = _to_double(value)
+        return number_to_string(number) if math.isfinite(number) else "null"
+    if isinstance(value, str):
+        return quote(value)
+    inner = None if indent is None else indent + "  "
+    if isinstance(value, Mapping):
+        mapping: Mapping[object, object] = value  # pyright: ignore[reportUnknownVariableType]
+        keys = [key for key in mapping if isinstance(key, str)]
+        if len(keys) != len(mapping):
+            raise TypeError("Object keys must be strings.")
+        members = [
+            (quote(key), _stringify(mapping[key], inner)) for key in js_key_order(keys) if mapping[key] is not UNDEFINED
+        ]
+        if not members:
+            return "{}"
+        if indent is None or inner is None:
+            return "{" + ",".join(f"{key}:{item}" for key, item in members) + "}"
+        return "{\n" + ",\n".join(f"{inner}{key}: {item}" for key, item in members) + "\n" + indent + "}"
+    if isinstance(value, list | tuple):
+        items: list[object] | tuple[object, ...] = value  # pyright: ignore[reportUnknownVariableType]
+        if not items:
+            return "[]"
+        if indent is None or inner is None:
+            return "[" + ",".join(_stringify(item, None) for item in items) + "]"
+        return "[\n" + ",\n".join(inner + _stringify(item, inner) for item in items) + "\n" + indent + "]"
+    raise TypeError(f"Cannot serialize {type(value).__name__} as JSON.")
+
+
+def _to_double(value: int | float) -> float:
+    try:
+        return float(value)
+    except OverflowError:
+        return math.inf if value > 0 else -math.inf
+
+
+def quote(text: str) -> str:
+    """JSON.stringify of a string: `"`, `\\`, and C0 controls escaped, lone surrogates as `\\udxxx`, the rest raw."""
+    return '"' + _NEEDS_ESCAPE.sub(_escape, text) + '"'
+
+
+def _escape(match: re.Match[str]) -> str:
+    chars = match.group()
+    if len(chars) == 2:
+        # A surrogate pair held as two code points is one well-formed character in JS.
+        return chr(0x10000 + ((ord(chars[0]) - 0xD800) << 10) + (ord(chars[1]) - 0xDC00))
+    return _ESCAPES.get(chars) or f"\\u{ord(chars):04x}"
+
+
+def js_key_order(keys: Iterable[str]) -> list[str]:
+    """Keys in JS own-property order: array indices (canonical integers up to 2**32 - 2) ascending, then the rest."""
+    indices: list[str] = []
+    others: list[str] = []
+    for key in keys:
+        (indices if _is_array_index(key) else others).append(key)
+    indices.sort(key=int)
+    return indices + others
+
+
+def _is_array_index(key: str) -> bool:
+    if not key.isascii() or not key.isdigit() or (len(key) > 1 and key[0] == "0"):
+        return False
+    return int(key) <= _MAX_ARRAY_INDEX
+
+
+def number_to_string(value: float) -> str:
+    """ECMAScript Number::toString(value) for radix 10."""
+    if math.isnan(value):
+        return "NaN"
+    if value == 0:
+        return "0"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    sign = "-" if value < 0 else ""
+    # repr gives the shortest digits that round-trip, as Number::toString requires.
+    mantissa, _, exponent = repr(abs(value)).partition("e")
+    whole, _, fraction = mantissa.partition(".")
+    digits = whole + fraction
+    point = len(whole) + (int(exponent) if exponent else 0)
+    stripped = digits.lstrip("0")
+    point -= len(digits) - len(stripped)
+    digits = stripped.rstrip("0")
+    k, n = len(digits), point
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * -n + digits
+    e = n - 1
+    head = digits[0] + ("." + digits[1:] if k > 1 else "")
+    return f"{sign}{head}e{'+' if e >= 0 else '-'}{abs(e)}"
+
+
+def to_fixed(value: float, digits: int = 2) -> str:
+    """`Number.prototype.toFixed(digits)`: round half away from zero on the exact binary value (quirk Q6).
+
+    `0.125` gives `"0.13"` where Python's `f"{0.125:.2f}"` gives `"0.12"`.
+    """
+    if not 0 <= digits <= 100:
+        raise ValueError("toFixed digits must be between 0 and 100.")
+    if not math.isfinite(value):
+        return number_to_string(value)
+    sign = "-" if value < 0 else ""
+    magnitude = abs(value)
+    if magnitude >= 1e21:
+        return sign + number_to_string(magnitude)
+    exact = Decimal(magnitude).quantize(Decimal(1).scaleb(-digits), rounding=ROUND_HALF_UP, context=_DECIMAL_CONTEXT)
+    return sign + format(exact, "f")
+
+
+_LOCALE_PLACES: Final = Decimal("0.001")
+
+
+def js_number_to_locale_string_en_us(value: float) -> str:
+    """`Number.prototype.toLocaleString("en-US")` with no options — a frozen JS behavior (ADR-0014).
+
+    Not an i18n API and never process-locale-dependent: the rules are pinned against the parity
+    Node (v24.19.0, ICU 78.3), which is where the reference's `200,000` rendering comes from. The
+    integer part is grouped in 3s with ","; a non-integer keeps at most 3 fraction digits
+    (maximumFractionDigits 3, minimumFractionDigits 0) rounded half away from zero on the shortest
+    round-trip digits — `(1.0005).toLocaleString("en-US")` is `"1.001"` although the double sits
+    below the midpoint. NaN and the infinities render as ICU does (`"NaN"`, `"∞"`, `"-∞"`). Grouping
+    never becomes exponent form (`1e21` renders `"1,000,000,000,000,000,000,000"`, unlike toFixed,
+    which switches to Number::toString at 1e21). Negative zero keeps its sign (`"-0"`), and a
+    negative magnitude that rounds away keeps it too (`(-0.0004)` → `"-0"`). An int is the double
+    JS would hold, as everywhere in this module: 123456789012345678901 groups as
+    `"123,456,789,012,345,680,000"`.
+    """
+    value = _to_double(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "∞" if value > 0 else "-∞"
+    sign = "-" if math.copysign(1.0, value) < 0 else ""
+    # V8/ICU round the shortest round-trip decimal (Number::toString digits), not the exact binary
+    # value; every form number_to_string emits, "1e+21" included, is a valid Decimal literal.
+    rounded = Decimal(number_to_string(abs(value))).quantize(
+        _LOCALE_PLACES, rounding=ROUND_HALF_UP, context=_DECIMAL_CONTEXT
+    )
+    whole, _, fraction = format(rounded, "f").partition(".")
+    fraction = fraction.rstrip("0")
+    return f"{sign}{int(whole):,}" + (f".{fraction}" if fraction else "")