Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat(serve): LAYA_JEV_STRICT projects the response onto the strict Jev wire contract

David Berardozzia8803529398c
diff --git a/docs/http-api.md b/docs/http-api.md
index 819307ce..ccb16aec 100644
--- a/docs/http-api.md
+++ b/docs/http-api.md
@@ -32,6 +32,7 @@ Everything is environment variables, so one image serves a laptop dev run and a
| `LAYA_API_KEY` | if set, require `Authorization: Bearer <key>` | none |
| `LAYA_LOG_LEVEL` | uvicorn log level | `info` |
| `LAYA_MAX_CONCURRENT` | requests admitted past auth at once; excess gets `503` | `16` |
+| `LAYA_JEV_STRICT` | serve the strict Jev wire contract: no root `routing`, no per-answer `action` / `answer_confidence`, no `confidence` on noul answers, and `usage` reduced to `input_tokens` + `output_tokens`. For clients that validate the response against the Jev contract with no extra fields | `0` |
For a deployment published under a prefix such as `/laya`, set `LAYA_ROOT_PATH=/laya`.
FastAPI uses it when generating OpenAPI and Swagger UI URLs. Configure the reverse proxy to
@@ -210,6 +211,31 @@ Never compare the two against one threshold. Also note the difference when porti
TypeSafe defines confidence as `(n*p_max - 1)/(n - 1)`, so a threshold carried over from a Jev
deployment gates differently on Laya's entropy value.
+### Strict Jev contract: `LAYA_JEV_STRICT`
+
+The payload above is the full Laya payload. The Jev contract a client may hold it to defines
+less: three top-level fields (`model`, `answers`, `usage`), the contracted keys on each answer
+and nothing else, and a `usage` of the two token counts. A client that validates the response
+against that contract with no extra fields -- OpenClaw's TypeSafe provider plugin is one --
+rejects the full payload, so `LAYA_JEV_STRICT=1` projects the response onto the contract before
+answering, on both `/v1/systemone` and `/v1/systemone/batch`:
+
+- the root keeps `model`, `answers` and `usage` only; `routing` is not sent;
+- a `choice` answer keeps `choice`, `probabilities` and `confidence`;
+- a `score` answer keeps `score`, `probabilities`, `confidence` and `legend`;
+- a `noul` answer keeps `noul` only;
+- `usage` keeps `input_tokens` and `output_tokens`; the truncation facts and the collapsed-
+ options ceiling are not sent.
+
+The projection keeps only the contracted keys and recomputes nothing: every value is the one the
+result already carries, so the probabilities and scores a strict client reads are identical to
+the ones the full payload reports. The default stays the full payload, and a deployment that
+turns the flag on loses the truncation visibility `usage` provides -- a cut state is then
+visible in the logs, not in the response. Score `criteria` should stay plain strings under the
+strict contract: a strict client compares the returned `legend` against the criteria it sent,
+and Laya renders a structured criterion with Python's JSON, which a JavaScript caller that
+stringifies its own criteria may not match byte for byte.
+
Successful responses also carry `Server-Timing: inference;dur=<ms>` and `X-Inference-Time-Ms`.
## Limits
diff --git a/laya/serve.py b/laya/serve.py
index 12254fae..0498b3bb 100644
--- a/laya/serve.py
+++ b/laya/serve.py
@@ -34,6 +34,11 @@ env var meaning defaul
``LAYA_MAX_CONCURRENT`` cap on requests past auth at once; excess 16
gets 503 (see below)
``LAYA_MAX_TOKEN_BUDGET`` cap on per-request max_len / head_max_len 8192
+``LAYA_JEV_STRICT`` if set, serve the strict Jev wire contract: no 0
+ root `routing`, no per-answer `action` /
+ `answer_confidence`, no `confidence` on noul
+ answers, and `usage` reduced to
+ `input_tokens` + `output_tokens`
========================= ============================================ =========
``LAYA_DEVICE`` is a preference, not a guarantee: an ``Agent`` that asks for a
@@ -120,6 +125,44 @@ def _env_bool(name: str, default: bool) -> bool:
return v.strip().lower() in ("1", "true", "yes", "on")
+def _project_jev_strict(result: Dict[str, Any]) -> Dict[str, Any]:
+ """Project a result onto the strict Jev wire contract (`LAYA_JEV_STRICT`).
+
+ The Jev `/v1/systemone` response defines exactly three top-level fields
+ (`model`, `answers`, `usage`), and each answer carries only its type's fields:
+ choice = `choice` + `probabilities` + `confidence`, score = `score` +
+ `probabilities` + `confidence` + `legend`, noul = `noul` only, and `usage` the
+ two token counts. Laya's full payload adds more: a root `routing` report, a
+ per-answer `action` head plus the calibrated `answer_confidence`, a
+ `confidence` on noul answers, and a usage report extended with the truncation
+ facts and the collapsed-options ceiling. Those additions are what a client
+ validating the response against the contract with no extra fields may reject,
+ so this keeps only the contracted keys. Nothing is recomputed: every value is
+ the one the result already carries, and an answer of an unknown shape passes
+ through unchanged so a caller still sees what it would have seen before.
+ """
+ answers: Dict[str, Any] = {}
+ for qid, answer in (result.get("answers") or {}).items():
+ kind = answer.get("type") if isinstance(answer, dict) else None
+ if kind == "choice":
+ answers[qid] = {"type": "choice", "choice": answer["choice"],
+ "confidence": answer["confidence"],
+ "probabilities": answer["probabilities"]}
+ elif kind == "score":
+ answers[qid] = {"type": "score", "score": answer["score"],
+ "confidence": answer["confidence"],
+ "probabilities": answer["probabilities"],
+ "legend": answer["legend"]}
+ elif kind == "noul":
+ answers[qid] = {"type": "noul", "noul": answer["noul"]}
+ else:
+ answers[qid] = answer
+ usage = result.get("usage") or {}
+ return {"model": result["model"], "answers": answers,
+ "usage": {"input_tokens": usage.get("input_tokens", 0),
+ "output_tokens": usage.get("output_tokens", 0)}}
+
+
def _published_model_ids() -> Dict[str, str]:
"""Public Hugging Face ids accepted so a client can name a checkpoint.
@@ -877,6 +920,8 @@ def create_app(router: Optional[Any] = None):
result = await loop.run_in_executor(
pool, lambda: router.predict(state, questions, model=model))
infer_ms = (time.perf_counter() - t0) * 1000.0
+ if _env_bool("LAYA_JEV_STRICT", False):
+ result = _project_jev_strict(result)
from fastapi.responses import JSONResponse
return JSONResponse(
content=result,
@@ -1002,6 +1047,8 @@ def create_app(router: Optional[Any] = None):
t0 = time.perf_counter()
batch_res = await loop.run_in_executor(pool, _do_batch)
infer_ms = (time.perf_counter() - t0) * 1000.0
+ if _env_bool("LAYA_JEV_STRICT", False):
+ batch_res["results"] = [_project_jev_strict(item) for item in batch_res["results"]]
from fastapi.responses import JSONResponse
return JSONResponse(
content=batch_res,
diff --git a/tests/test_serve.py b/tests/test_serve.py
index 155aeffb..7b419320 100644
--- a/tests/test_serve.py
+++ b/tests/test_serve.py
@@ -135,6 +135,123 @@ def test_predict_passthrough_shape(monkeypatch):
assert fake.calls[0]["model"] is None
+# A router that answers with the full Laya payload: every answer type, the per-answer
+# additions and the extended usage report -- what a strict client must be projected off.
+FULL_ANSWERS = {
+ "queue": {"type": "choice", "choice": "billing",
+ "probabilities": {"billing": 0.9519, "tech": 0.0327, "other": 0.0154},
+ "confidence": 0.797, "answer_confidence": 0.9519,
+ "action": {"act_probability": 1.0}},
+ "urgency": {"type": "score", "score": 1.6994,
+ "legend": {"0": "calm", "1": "firm", "2": "angry"},
+ "probabilities": {"0": 0.0249, "1": 0.65, "2": 0.3251},
+ "confidence": 0.1925, "answer_confidence": 0.65,
+ "action": {"act_probability": 0.5}},
+ "threat": {"type": "noul", "noul": 0.9148, "confidence": 0.9148,
+ "answer_confidence": 0.9148, "action": {"act_probability": 1.0}},
+}
+FULL_USAGE = {"input_tokens": 83, "output_tokens": 0, "state_tokens": 12,
+ "state_tokens_dropped": 0, "truncated": False, "truncated_questions": []}
+
+
+class StrictFullRouter:
+ """Returns the full payload, additions and all, whatever the request."""
+
+ loaded = ["english"]
+
+ def __init__(self):
+ self.calls = []
+
+ def predict(self, state, questions, model=None):
+ self.calls.append({"state": state, "questions": questions, "model": model})
+ return {"model": "laya-rl-agent", "answers": FULL_ANSWERS, "usage": dict(FULL_USAGE),
+ "routing": {"model": "english", "reason": "English Latin text"}}
+
+ def predict_batch(self, requests, **kwargs):
+ return [self.predict(item["state"], item["questions"], model=item.get("model"))
+ for item in requests]
+
+
+def _strict_client(monkeypatch, value):
+ if value is None:
+ monkeypatch.delenv("LAYA_JEV_STRICT", raising=False)
+ else:
+ monkeypatch.setenv("LAYA_JEV_STRICT", value)
+ fake = StrictFullRouter()
+ return TestClient(create_app(router=fake)), fake
+
+
+def test_jev_strict_projects_the_full_payload(monkeypatch):
+ client, _ = _strict_client(monkeypatch, "1")
+ r = client.post("/v1/systemone", json=REQ)
+ assert r.status_code == 200
+ body = r.json()
+ # the strict contract: exactly three top-level fields, the contracted answer keys
+ assert set(body) == {"model", "answers", "usage"}
+ assert body["model"] == "laya-rl-agent"
+ assert body["answers"]["queue"] == {"type": "choice", "choice": "billing",
+ "confidence": 0.797,
+ "probabilities": {"billing": 0.9519, "tech": 0.0327,
+ "other": 0.0154}}
+ assert body["answers"]["urgency"] == {"type": "score", "score": 1.6994,
+ "confidence": 0.1925,
+ "probabilities": {"0": 0.0249, "1": 0.65, "2": 0.3251},
+ "legend": {"0": "calm", "1": "firm", "2": "angry"}}
+ assert body["answers"]["threat"] == {"type": "noul", "noul": 0.9148}
+ # usage reduced to the two contracted counts, with the values the result carried
+ assert body["usage"] == {"input_tokens": 83, "output_tokens": 0}
+
+
+def test_jev_strict_is_off_by_default(monkeypatch):
+ """No flag: the full payload, additions and all, byte for byte."""
+ client, _ = _strict_client(monkeypatch, None)
+ body = client.post("/v1/systemone", json=REQ).json()
+ assert set(body) == {"model", "answers", "usage", "routing"}
+ assert "action" in body["answers"]["queue"]
+ assert "confidence" in body["answers"]["threat"]
+ assert body["usage"] == FULL_USAGE
+
+
+def test_jev_strict_rejects_falsy_spellings(monkeypatch):
+ client, _ = _strict_client(monkeypatch, "0")
+ body = client.post("/v1/systemone", json=REQ).json()
+ assert "routing" in body
+
+
+def test_jev_strict_batch_projects_every_item(monkeypatch):
+ client, fake = _strict_client(monkeypatch, "1")
+ r = client.post("/v1/systemone/batch", json={"states": ["one", "two"],
+ "questions": REQ["questions"]})
+ assert r.status_code == 200
+ data = r.json()
+ assert [set(item) for item in data["results"]] == [
+ {"model", "answers", "usage"}, {"model", "answers", "usage"}]
+ assert all("routing" not in item for item in data["results"])
+ assert all(item["usage"] == {"input_tokens": 83, "output_tokens": 0}
+ for item in data["results"])
+ # total_usage is the batch envelope's own, untouched by the projection
+ assert data["total_usage"] == {"input_tokens": 166, "output_tokens": 0}
+
+
+def test_jev_strict_leaves_an_unknown_answer_shape_unchanged(monkeypatch):
+ """A shape the contract does not name is passed through: the caller still sees it."""
+ monkeypatch.setenv("LAYA_JEV_STRICT", "1")
+ monkeypatch.delenv("LAYA_API_KEY", raising=False)
+
+ class OddRouter:
+ loaded = ["english"]
+
+ def predict(self, state, questions, model=None):
+ return {"model": "laya-rl-agent",
+ "answers": {"odd": {"type": "weird", "payload": 1}},
+ "usage": {"input_tokens": 1, "output_tokens": 0}}
+
+ client = TestClient(create_app(router=OddRouter()))
+ body = client.post("/v1/systemone", json=REQ).json()
+ assert body["answers"]["odd"] == {"type": "weird", "payload": 1}
+ assert "routing" not in body
+
+
def test_known_model_is_honoured(monkeypatch):
client, fake = _client(monkeypatch)
client.post("/v1/systemone", json={**REQ, "model": "multilingual"})