@plumbus/ai-decision-laya 0.2.0

package/dist/laya-adapter.d.ts

@@ -0,0 +1,11 @@
+import { type DecisionHttpConfig, type DecisionProviderAdapter } from '@plumbus/ai-decision';
+export interface LayaDecisionAdapterConfig extends DecisionHttpConfig {
+    /** auto routes by language; otherwise selects a configured checkpoint. */
+    model?: string;
+    language?: string;
+    /** Operator-supplied infrastructure estimate. Omit to report unknown cost. */
+    costPerRequestUsd?: number;
+}
+/** Calls the persistent Python service shipped in this package's service/ directory. */
+export declare function createLayaDecisionAdapter(config: LayaDecisionAdapterConfig): DecisionProviderAdapter;
+//# sourceMappingURL=laya-adapter.d.ts.map

package/dist/laya-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"laya-adapter.d.ts","sourceRoot":"","sources":["../src/laya-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,yBAAyB,GAChC,uBAAuB,CAgDzB"}

package/dist/laya-adapter.js

@@ -0,0 +1,41 @@
+import { createDecisionHttpTransport, DecisionProviderError, parseDecisionResponse, toSystemOneQuestions, validateDecisionRequest, } from '@plumbus/ai-decision';
+import { z } from '@plumbus/core/zod';
+/** Calls the persistent Python service shipped in this package's service/ directory. */
+export function createLayaDecisionAdapter(config) {
+    const settings = z
+        .object({
+        model: z.string().trim().min(1).max(256).default('auto'),
+        language: z.string().trim().min(1).max(64).optional(),
+        costPerRequestUsd: z.number().finite().nonnegative().optional(),
+    })
+        .safeParse(config);
+    if (!settings.success)
+        throw new DecisionProviderError('laya', 'configuration', 'Invalid Laya model, language, or cost configuration');
+    const post = createDecisionHttpTransport('laya', config);
+    return {
+        name: 'laya',
+        async decide(request) {
+            const input = validateDecisionRequest(request, 'laya');
+            const start = performance.now();
+            const model = input.model ?? settings.data.model;
+            const wire = await post({
+                state: input.state,
+                questions: toSystemOneQuestions(input.questions),
+                ...(model === 'auto' ? {} : { model }),
+                ...(settings.data.language ? { lang: settings.data.language } : {}),
+            }, input);
+            const result = parseDecisionResponse(wire, input.questions, 'laya');
+            if (!z.object({ routing: z.object({}) }).safeParse(result).success) {
+                throw new DecisionProviderError('laya', 'invalid_response', 'Laya response is missing checkpoint routing identity', { model: result.model, usage: result.usage });
+            }
+            const cost = settings.data.costPerRequestUsd ?? null;
+            return {
+                ...result,
+                cost,
+                costAvailable: cost !== null,
+                latencyMs: performance.now() - start,
+            };
+        },
+    };
+}
+//# sourceMappingURL=laya-adapter.js.map

package/dist/laya-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"laya-adapter.js","sourceRoot":"","sources":["../src/laya-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,GAGxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAUtC,wFAAwF;AACxF,MAAM,UAAU,yBAAyB,CACvC,MAAiC;IAEjC,MAAM,QAAQ,GAAG,CAAC;SACf,MAAM,CAAC;QACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;QACrD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;KAChE,CAAC;SACD,SAAS,CAAC,MAAM,CAAC,CAAC;IACrB,IAAI,CAAC,QAAQ,CAAC,OAAO;QACnB,MAAM,IAAI,qBAAqB,CAC7B,MAAM,EACN,eAAe,EACf,qDAAqD,CACtD,CAAC;IACJ,MAAM,IAAI,GAAG,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK,CAAC,MAAM,CAAC,OAAO;YAClB,MAAM,KAAK,GAAG,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YACjD,MAAM,IAAI,GAAG,MAAM,IAAI,CACrB;gBACE,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,SAAS,EAAE,oBAAoB,CAAC,KAAK,CAAC,SAAS,CAAC;gBAChD,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;gBACtC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpE,EACD,KAAK,CACN,CAAC;YACF,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACpE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;gBACnE,MAAM,IAAI,qBAAqB,CAC7B,MAAM,EACN,kBAAkB,EAClB,sDAAsD,EACtD,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAC7C,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC;YACrD,OAAO;gBACL,GAAG,MAAM;gBACT,IAAI;gBACJ,aAAa,EAAE,IAAI,KAAK,IAAI;gBAC5B,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK;aACrC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/instructions/README.md

@@ -0,0 +1,12 @@
+# @plumbus/ai-decision-laya — agent instructions
+
+| File | When to read |
+| --- | --- |
+| [framework.md](framework.md) | Installation, public exports, adapter boundary, usage rules |
+| [testing.md](testing.md) | Offline validation and live environment setup |
+
+Keep app business logic in Plumbus primitives and `ctx.*`. These packages do not
+add `ctx.ai.decide()` or automatic provider discovery yet. Never route model
+predictions directly around capability access checks or confirmation policy.
+
+[Package README](../README.md) · [Monorepo guide](https://github.com/plumbus-framework/plumbus/blob/main/docs/ai/decision-providers.md)

package/instructions/framework.md

@@ -0,0 +1,46 @@
+# Framework boundary
+
+Laya provider for self-hosted typed decision inference, with a persistent Python reference service.
+
+## Install and ownership
+
+Install `@plumbus/ai-decision-laya` explicitly. Its core peer is exactly `"0.7.x"`.
+Consumers reuse Zod/testing utilities from core; do not install them separately.
+Use this package for bounded typed decisions. Use core generation and embeddings
+for text responses and vector inference.
+
+Public exports: `createLayaDecisionAdapter` — construct an explicitly configured adapter; `DecisionProviderError` — structured failures; `DecisionProviderAdapter`, `DecisionQuestions`, `DecisionRequest`, `DecisionResult` — protocol types.
+
+File map: `src/index.ts` is the public barrel, `src/__tests__/` exercises the public
+API, `instructions/` contains these recipes. Laya alone also ships `service/`.
+
+## Minimal usage
+
+```ts
+import { createLayaDecisionAdapter } from '@plumbus/ai-decision-laya';
+
+const adapter = createLayaDecisionAdapter({ baseUrl: 'http://127.0.0.1:8080/v1', apiKey: process.env.LAYA_API_KEY });
+const result = await adapter.decide({
+  state: 'Please refund the duplicate charge.',
+  questions: { refund: { type: 'probability', instructions: 'Is a refund requested?' } },
+});
+console.log(result.answers.refund.probability);
+```
+
+
+## Required rules
+
+1. Keep capabilities, flows, access policy and `ctx.*` as the application implementation path.
+2. Construct adapters at a server-owned infrastructure boundary and inject them. Keep keys on the server.
+3. Treat direct adapter usage as protocol integration, not a replacement for core's security/budget/audit lifecycle.
+4. Do not monkeypatch `ctx.ai`, register these as completion providers, or advertise `ctx.ai.decide()` as available.
+5. Preserve distributions and provider confidence separately. A high confidence value is not authorization or proof of correctness.
+6. Validate thresholds on the actual task/model/language. Unknown cost is `null`, not free.
+7. Pass cancellation/deadlines explicitly during this package-only stage.
+8. Keep Python inference outside Node.js. Use the packaged Laya service or implement its documented HTTP protocol.
+9. There are no core CLI commands, environment discovery, or `plumbus init` instruction wiring for these packages yet.
+
+Chat, voice and MCP still consume Plumbus capabilities; this package does not
+introduce a parallel runtime or transport for those surfaces.
+
+See `docs/ai/decision-providers.md` in the monorepo for the full API and configuration.

package/instructions/testing.md

@@ -0,0 +1,19 @@
+# Testing
+
+Use injected `fetch` for offline adapter tests. In consumer applications, test
+business behavior through core's `runCapability()` / `simulateFlow()` and run
+`plumbus test`; do not add separate Vitest or Zod dependencies.
+
+In the framework repository, run `pnpm lint`, `pnpm format:check`,
+`pnpm typecheck`, and `pnpm test`. Laya's offline service contract test needs
+`python3` but imports no model libraries and downloads nothing.
+
+For live tests, follow [Providing a live test environment](https://github.com/plumbus-framework/plumbus/blob/main/docs/ai/decision-providers.md#providing-a-live-test-environment).
+Provide a private env-file path, not pasted secrets. Set
+`PLUMBUS_LIVE_DECISION_TESTS=1`, the provider key, and the reachable Laya base URL
+when applicable. Run the provider's `scripts/smoke.mjs` from its monorepo directory
+after building. Scripts are repository tools, not installed core CLI commands.
+
+Validate choices, scores, probabilities, actual model/routing, usage and unknown
+cost handling. Measure live accuracy and calibration separately from connection
+success. Do not assert a universal confidence cutoff or guaranteed live label.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@plumbus/ai-decision-laya",
+  "version": "0.2.0",
+  "description": "Self-hosted Laya typed decision adapter and Python reference service for Plumbus.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "instructions",
+    "README.md",
+    "CHANGELOG.md",
+    "service"
+  ],
+  "keywords": [
+    "plumbus",
+    "ai",
+    "decision"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plumbus-framework/plumbus.git",
+    "directory": "packages/ai-decision-laya"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "peerDependencies": {
+    "@plumbus/core": "0.7.x"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^25.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4",
+    "@plumbus/core": "0.7.2"
+  },
+  "dependencies": {
+    "@plumbus/ai-decision": "~0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "vitest run",
+    "lint": "biome lint ./src",
+    "format": "biome format --write ./src",
+    "format:check": "biome format ./src",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "smoke": "pnpm build && node scripts/smoke.mjs"
+  }
+}

package/service/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+WORKDIR /service
+COPY requirements.txt .
+# CPU reference image. GPU environments should provision their CUDA-compatible torch separately.
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r requirements.txt
+COPY server.py .
+RUN useradd --create-home laya \
+    && mkdir -p /home/laya/.cache/huggingface \
+    && chown -R laya:laya /home/laya/.cache
+USER laya
+ENV LAYA_HOST=0.0.0.0 LAYA_PORT=8080 LAYA_DEVICE=cpu HF_HOME=/home/laya/.cache/huggingface
+EXPOSE 8080
+CMD ["python", "server.py"]

package/service/fixtures/fake_server.py

@@ -0,0 +1,28 @@
+"""E2E-only inference fixture. This module is never used by the production entrypoint."""
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from server import create_server
+
+
+class Backend:
+    names = ("english", "multilingual")
+
+    def predict(self, body):
+        answers = {}
+        for key, question in body["questions"].items():
+            if question["type"] == "noul":
+                answers[key] = {"type": "noul", "noul": 0.75, "confidence": 0.75}
+            elif question["type"] == "choice":
+                labels = list(question["criteria"])
+                answers[key] = {"type": "choice", "choice": labels[0], "confidence": 1, "probabilities": {label: int(i == 0) for i, label in enumerate(labels)}}
+            else:
+                answers[key] = {"type": "score", "score": 1, "confidence": 1, "legend": {str(i): v for i, v in enumerate(question["criteria"])}, "probabilities": {str(i): int(i == 1) for i, _ in enumerate(question["criteria"])}}
+        return {"model": "fixture", "answers": answers, "usage": {"input_tokens": 12, "output_tokens": 0}, "routing": {"model": body.get("model", "multilingual"), "repo": "fixture", "reason": "Fixture routing"}}
+
+
+server = create_server(("127.0.0.1", 0), Backend(), "e2e-key")
+print(json.dumps({"port": server.server_address[1]}), flush=True)
+server.serve_forever()

package/service/requirements.txt

@@ -0,0 +1,2 @@
+# Inference dependencies are installed only in the separately deployed Python service.
+laya==0.3.5

package/service/server.py

@@ -0,0 +1,287 @@
+"""Small, authenticated Laya HTTP service; inference stays outside Node.js.
+
+Run one process per device. The lock serializes inference and checkpoint access.
+Only configured, preloaded checkpoints are served; no request downloads models.
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+import math
+import os
+import re
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+MAX_BODY_BYTES = 2 * 1024 * 1024
+
+
+class RequestError(Exception):
+    """A safe client error; never put submitted state or credentials in its text."""
+
+
+def validate_json(value, depth=0):
+    """JSON decoder extensions and invalid Unicode must not reach the model."""
+    if depth > 64:
+        raise RequestError("JSON nesting exceeds 64 levels")
+    if isinstance(value, str):
+        try:
+            value.encode("utf-8", errors="strict")
+        except UnicodeError as error:
+            raise RequestError("Invalid Unicode in JSON") from error
+    elif isinstance(value, (int, float)):
+        try:
+            if not math.isfinite(value):
+                raise RequestError("Non-finite numbers are not JSON")
+        except OverflowError as error:
+            raise RequestError("Number exceeds the supported range") from error
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            validate_json(key, depth + 1)
+            validate_json(item, depth + 1)
+    elif isinstance(value, list):
+        for item in value:
+            validate_json(item, depth + 1)
+
+
+def unique_object(pairs):
+    value = {}
+    for key, item in pairs:
+        if key in value:
+            raise RequestError("Duplicate JSON keys are not supported")
+        value[key] = item
+    return value
+
+
+def check_token_budget(agent, state, questions, render_options, serialize_state):
+    """Reject truncation using the formatting/token budgets of pinned Laya 0.3.5.
+
+    This deliberately rejects long option descriptions even if their distinguishing
+    words happen to fit. Updating Laya requires revalidating this boundary.
+    """
+    tok = agent.tok
+    mask = tok.mask_token
+    max_len = agent.cfg.get("max_len", 512)
+    head_max_len = agent.cfg.get("head_max_len", 192)
+    state_tokens = tok(serialize_state(state).replace(mask, " "), add_special_tokens=False)["input_ids"]
+    for question in questions.values():
+        internal = agent._to_internal(question)
+        instructions = str(internal["ins"]).replace(mask, " ")
+        head = tok(f"{internal['t']} question: {instructions}", add_special_tokens=False)["input_ids"]
+        options = [
+            tok(" " + option.replace(mask, " "), add_special_tokens=False)["input_ids"]
+            for option in render_options(internal)
+        ]
+        option_size = sum(len(option) + 1 for option in options)
+        remaining = head_max_len - option_size
+        if any(len(option) > 48 for option in options) or remaining < 16 or len(head) > max(8, remaining):
+            raise RequestError("Question exceeds the checkpoint instruction/option token budget")
+        if len(head) + option_size + len(state_tokens) + 4 > max_len:
+            raise RequestError("State exceeds the checkpoint token budget; shorten the supplied state")
+
+
+class LayaBackend:
+    def __init__(self):
+        # Importing this module and running service contract tests never downloads weights.
+        from laya import Router
+        from laya.common import render_options, serialize_state
+
+        names = [name.strip() for name in os.environ.get("LAYA_MODELS", "english").split(",")]
+        if not names or any(name not in {"english", "multilingual", "typed-decisions"} for name in names):
+            raise RequestError("LAYA_MODELS must list english, multilingual, and/or typed-decisions")
+        self.names = tuple(dict.fromkeys(names))
+        self.router = Router(device=os.environ.get("LAYA_DEVICE", "cpu"), max_loaded=len(self.names))
+        self.router.preload(list(self.names))
+        self.render_options = render_options
+        self.serialize_state = serialize_state
+        self.lock = threading.Lock()
+
+    def predict(self, body):
+        # Reject rather than queue unbounded inference behind one busy device.
+        if not self.lock.acquire(blocking=False):
+            return None
+        try:
+            try:
+                decision = self.router.route(body["state"], body["questions"], model=body.get("model"), lang=body.get("lang"))
+            except ValueError as error:
+                raise RequestError("Invalid checkpoint selection") from error
+            if decision.model not in self.names:
+                raise RequestError("Selected checkpoint is not preloaded; configure LAYA_MODELS or select a loaded model")
+            agent = self.router.load(decision.model)
+            check_token_budget(agent, body["state"], body["questions"], self.render_options, self.serialize_state)
+            result = agent.predict(body["state"], body["questions"])
+            result["routing"] = dict(decision)
+            return result
+        finally:
+            self.lock.release()
+
+
+def validate_body(body):
+    # The HTTP boundary also validates callers that do not use the TypeScript adapter.
+    validate_json(body)
+    if not isinstance(body, dict) or set(body) - {"state", "questions", "model", "lang"}:
+        raise RequestError("Invalid request object")
+    if not isinstance(body.get("state"), (str, dict, list)):
+        raise RequestError("state must be a string, object, or array")
+    questions = body.get("questions")
+    if not isinstance(questions, dict) or not 1 <= len(questions) <= 256:
+        raise RequestError("Provide 1–256 questions")
+    for field in ("model", "lang"):
+        if field in body and (not isinstance(body[field], str) or not body[field].strip() or not 1 <= len(body[field]) <= 256):
+            raise RequestError("Invalid model or language")
+    for key, question in questions.items():
+        if not key or not isinstance(question, dict) or set(question) - {"type", "instructions", "criteria"}:
+            raise RequestError("Invalid question")
+        if not isinstance(question.get("instructions"), (str, dict, list)):
+            raise RequestError("Invalid question instructions")
+        kind, criteria = question.get("type"), question.get("criteria")
+        if kind == "choice":
+            if not isinstance(criteria, dict) or not 2 <= len(criteria) <= 255 or any(not k for k in criteria):
+                raise RequestError("Choice requires 2–255 options")
+            if any(v is not None and not isinstance(v, (str, dict, list)) for v in criteria.values()):
+                raise RequestError("Invalid choice criteria")
+        elif kind == "score":
+            if not isinstance(criteria, list) or not 2 <= len(criteria) <= 10 or any(not isinstance(v, (str, dict, list)) for v in criteria):
+                raise RequestError("Score requires 2–10 descriptive levels")
+        elif kind == "noul":
+            if criteria is not None and (not isinstance(criteria, dict) or set(criteria) - {"true", "false"} or any(not isinstance(v, (str, dict, list)) for v in criteria.values())):
+                raise RequestError("Invalid noul criteria")
+        else:
+            raise RequestError("Unsupported question type")
+    return body
+
+
+class BoundedHTTPServer(ThreadingHTTPServer):
+    """Limit active handlers before spawning threads, including slow request readers."""
+
+    def __init__(self, address, handler, max_connections):
+        self._connection_slots = threading.BoundedSemaphore(max_connections)
+        super().__init__(address, handler)
+
+    def process_request(self, request, client_address):
+        if not self._connection_slots.acquire(blocking=False):
+            payload = b'{"error":"Service connection capacity reached"}'
+            response = (b"HTTP/1.0 503 Service Unavailable\r\nContent-Type: application/json\r\n"
+                        b"Connection: close\r\nRetry-After: 1\r\nContent-Length: "
+                        + str(len(payload)).encode() + b"\r\n\r\n" + payload)
+            try:
+                request.settimeout(0.5)
+                request.sendall(response)
+            except OSError:
+                pass
+            finally:
+                self.shutdown_request(request)
+            return
+        try:
+            super().process_request(request, client_address)
+        except BaseException:
+            self._connection_slots.release()
+            raise
+
+    def process_request_thread(self, request, client_address):
+        try:
+            super().process_request_thread(request, client_address)
+        finally:
+            self._connection_slots.release()
+
+
+def create_server(address, backend, api_key, *, max_connections=32):
+    if not api_key or not re.fullmatch(r"[\x21-\x7e]+", api_key):
+        raise RequestError("Set LAYA_API_KEY to a nonempty printable ASCII token without whitespace")
+    if isinstance(max_connections, bool) or not isinstance(max_connections, int) or not 1 <= max_connections <= 128:
+        raise RequestError("max_connections must be an integer from 1 to 128")
+
+    class Handler(BaseHTTPRequestHandler):
+        def setup(self):
+            super().setup()
+            self.connection.settimeout(30)
+
+        def respond(self, status, payload):
+            data = json.dumps(payload, ensure_ascii=False, allow_nan=False).encode()
+            if len(data) > MAX_BODY_BYTES:
+                raise RuntimeError("Inference response exceeds the service limit")
+            try:
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                if status == 503:
+                    self.send_header("Retry-After", "1")
+                self.end_headers()
+                self.wfile.write(data)
+            except (BrokenPipeError, ConnectionResetError, TimeoutError):
+                pass  # A cancelled HTTP request cannot interrupt an active GPU kernel.
+
+        def do_GET(self):
+            self.respond(200, {"ready": True, "models": backend.names}) if self.path == "/healthz" else self.respond(404, {"error": "Not found"})
+
+        def do_POST(self):
+            if self.path != "/v1/systemone":
+                return self.respond(404, {"error": "Not found"})
+            expected = api_key.encode()
+            auth_headers = self.headers.get_all("Authorization", [])
+            auth = re.fullmatch(r"(?i:Bearer) +([\x21-\x7e]+)", auth_headers[0]) if len(auth_headers) == 1 else None
+            supplied = auth.group(1).encode() if auth else b""
+            if not hmac.compare_digest(expected, supplied):
+                return self.respond(401, {"error": "Unauthorized"})
+            if self.headers.get("Transfer-Encoding"):
+                return self.respond(400, {"error": "Chunked requests are not supported"})
+            lengths = self.headers.get_all("Content-Length", [])
+            if len(lengths) != 1 or not re.fullmatch(r"[0-9]+", lengths[0]) or len(lengths[0]) > 10:
+                return self.respond(400, {"error": "Provide exactly one valid Content-Length"})
+            length = int(lengths[0])
+            if not 0 < length <= MAX_BODY_BYTES:
+                return self.respond(413, {"error": "Provide a JSON body of at most 2 MiB"})
+            encodings = self.headers.get_all("Content-Encoding", [])
+            if len(encodings) > 1 or (encodings and encodings[0].strip().lower() != "identity"):
+                return self.respond(415, {"error": "Unsupported Content-Encoding"})
+            content_types = self.headers.get_all("Content-Type", [])
+            if len(content_types) != 1 or content_types[0].split(";", 1)[0].strip().lower() != "application/json":
+                return self.respond(415, {"error": "Content-Type must be application/json"})
+            try:
+                def reject_constant(_value):
+                    raise RequestError("Non-finite numbers are not JSON")
+                data = self.rfile.read(length)
+                if len(data) != length:
+                    return self.respond(400, {"error": "Incomplete request body"})
+                body = validate_body(json.loads(data.decode("utf-8", errors="strict"), parse_constant=reject_constant, object_pairs_hook=unique_object))
+            except (RequestError, ValueError, RecursionError):
+                return self.respond(422, {"error": "Invalid JSON decision request"})
+            except TimeoutError:
+                return self.respond(408, {"error": "Request body timed out"})
+            try:
+                result = backend.predict(body)
+                if result is None:
+                    return self.respond(503, {"error": "Inference device busy"})
+                self.respond(200, result)
+            except RequestError:
+                self.respond(422, {"error": "Invalid request or checkpoint token budget exceeded"})
+            except Exception:
+                self.respond(500, {"error": "Laya inference failed"})
+
+        def log_message(self, _format, *_args):
+            pass  # Request bodies, API keys, and submitted text are never logged.
+
+    return BoundedHTTPServer(address, Handler, max_connections)
+
+
+if __name__ == "__main__":
+    key = os.environ.get("LAYA_API_KEY", "")
+    if not key or not re.fullmatch(r"[\x21-\x7e]+", key):
+        raise SystemExit("Set LAYA_API_KEY to a printable ASCII token without whitespace before starting the service")
+    try:
+        capacity = int(os.environ.get("LAYA_MAX_CONNECTIONS", "32"))
+        if not 1 <= capacity <= 128:
+            raise ValueError
+    except ValueError:
+        raise SystemExit("LAYA_MAX_CONNECTIONS must be an integer from 1 to 128") from None
+    backend = LayaBackend()
+    server = create_server((os.environ.get("LAYA_HOST", "127.0.0.1"), int(os.environ.get("LAYA_PORT", "8080"))), backend, key, max_connections=capacity)
+    print(f"Laya ready on {server.server_address[0]}:{server.server_address[1]}; checkpoints: {', '.join(backend.names)}", flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()