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(mcp): register laya_tournament and advertise its contract

Rishit Sharma0764f28bb8c3
diff --git a/docs/cli-mcp.md b/docs/cli-mcp.md
index 8e5cb45c..9703dc7b 100644
--- a/docs/cli-mcp.md
+++ b/docs/cli-mcp.md
@@ -161,6 +161,7 @@ Laya does not open a network port.
| `laya_route` | Selects a checkpoint and returns its model, repository, and reason without running a forward pass. | `state`, `questions`, optional `model`, `task`, `lang`, `lang_guess` |
| `laya_predict` | Runs typed questions and returns answers, routing metadata, latency, and the answering device when readable. | `state`, `questions`, optional `model` (`auto`, `english`, `multilingual`, or `typed-decisions`), `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence` |
| `laya_shortlist` | Shortlists a many-option choice question, then answers it and returns the shortlist metadata. | `state`, `questions`, optional `model`, `k` (default `20`), `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence` |
+| `laya_tournament` | Narrows large choices in balanced rounds using the decision model, then answers the complete request. In-process only. | `state`, `questions`, optional `model`, `group_size` (default `16`), `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence` |
| `laya_preset` | Runs a built-in workflow using its built-in question set. | `preset`, `state`, optional `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence` |
| `laya_predict_batch` | Answers many requests in one call. Requests are routed first and grouped by checkpoint, so matching question schemas share forward passes; answers come back in input order. | `requests`, each `{state, questions, model?, task?, lang?, lang_guess?, max_len?, head_max_len?}`, optional `batch_size`, `hooks_timeout`, `min_confidence`, `sort_by_length` |
| `laya_route_batch` | Decides which checkpoint would answer each request, with no forward pass and no checkpoint load. | `requests`, each `{state, questions, model?, task?, lang?, lang_guess?}`, optional `hooks_timeout` |
diff --git a/laya/mcp/server.py b/laya/mcp/server.py
index a780b4bd..f7baa03c 100644
--- a/laya/mcp/server.py
+++ b/laya/mcp/server.py
@@ -57,6 +57,7 @@ from .tools import (
laya_route_batch,
laya_shortlist,
laya_status,
+ laya_tournament,
)
try:
@@ -83,7 +84,7 @@ _GUARDRAILS = (
"noul (calibrated P(true)). One forward pass ~33ms (GPU) / ~200ms (CPU). "
"No text generation, so no hallucination. Do NOT use for open Q&A, summarization, "
"rewriting, code, or multi-hop reasoning. Do NOT use for >20-option choice "
- "questions without shortlisting (use the laya_shortlist tool)."
+ "questions without narrowing (use laya_shortlist or laya_tournament)."
)
# The `model` argument's contract, spelled out for clients because the tools take a free string.
@@ -396,7 +397,7 @@ def laya_route_batch_tool(requests: list, hooks_timeout: float = 0) -> str:
"Shortlist a many-option choice question to its k most likely labels by embedding "
"similarity (mean-pooled from the answering checkpoint's own encoder, so no extra "
"model is downloaded), then answer in one forward pass. Use this instead of "
- "laya_predict whenever a choice question has more options than the guardrails allow. "
+ "laya_predict when embedding similarity is appropriate for narrowing a large choice. "
"Returns the answers plus per-question shortlist metadata (kept labels, cosine "
"scores, k, option count, and whether the question passed through unshortlisted). "
"Shortlisting narrows the label set; head_max_len decides how many tokens each kept label "
@@ -444,6 +445,55 @@ def laya_shortlist_tool(
)
+ name="laya_tournament",
+ description=(
+ "Answer large choice questions by balanced elimination with the decision model, without "
+ "embeddings. group_size: integer at least 2, default 16. All groups share one forward "
+ "pass per round; their winners advance until they fit, then one final pass answers the "
+ "complete request. Small choices and non-choice questions pass through. Returns answers, "
+ "routing, total latency_ms, the answering device when readable, and tournament metadata "
+ "per choice: labels (finalists in criteria order), n (original option count), rounds "
+ "(elimination rounds, zero on passthrough). Probabilities and confidence are over the "
+ "finalists only; thresholds fitted on a full option set do not transfer. A narrowed "
+ "question's option_order is dropped and reported under option_order_dropped with n and "
+ "kept counts. In-process only: with LAYA_BASE_URL set, use laya_predict with the HTTP "
+ "server's LAYA_TOURNAMENT_GROUP enabled instead. "
+ + _GUARDRAILS
+ + _MODEL_DOC
+ + _CONTROLS_DOC
+ ),
+)
+def laya_tournament_tool(
+ state: dict,
+ questions: dict,
+ model: str | None = None,
+ group_size: int = 16,
+ task: str | None = None,
+ lang: str | None = None,
+ lang_guess: str | None = None,
+ max_len: int | None = None,
+ head_max_len: int | None = None,
+ min_confidence: float | None = None,
+) -> str:
+ """Answer many-option choices with balanced tournament rounds."""
+ router = _ensure_router()
+ return _wrap(
+ laya_tournament,
+ state=state,
+ questions=questions,
+ model=model,
+ group_size=group_size,
+ task=task,
+ lang=lang,
+ lang_guess=lang_guess,
+ max_len=max_len,
+ head_max_len=head_max_len,
+ min_confidence=min_confidence,
+ router=router,
+ )
+
+
_PRESET_INFO = get_available_presets()
# Built from tools.get_available_presets() rather than typed out, because the names in a
diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py
index 9c7a7714..c61c671e 100644
--- a/tests/test_hooks_api.py
+++ b/tests/test_hooks_api.py
@@ -116,6 +116,14 @@ for param in ("state", "questions"):
for param in ("task", "lang", "lang_guess", "max_len", "head_max_len", "min_confidence", "router", "agent"):
check_param("laya_tournament", laya_tournament, param, None, inspect.Parameter.KEYWORD_ONLY)
+if _mcp_batch_tool is not None:
+ from laya.mcp.server import laya_tournament_tool # noqa: E402
+
+ check_param("laya_tournament_tool", laya_tournament_tool, "group_size",
+ sig(laya.predict_tournament)["group_size"].default)
+ for param in ("model", "task", "lang", "lang_guess", "max_len", "head_max_len", "min_confidence"):
+ check_param("laya_tournament_tool", laya_tournament_tool, param, None)
+
# What the constructor does NOT raise over is part of its contract too: a shared
# `agent_kwargs["expected_sha256"]` overlapping a per-checkpoint `sha256_digests` entry on one file
# name is the ordinary shape, not a contradiction -- `model.safetensors` is the one name every
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index 9d834773..ad79529d 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -2085,7 +2085,7 @@ def test_controls_signature_and_schema():
import inspect
controls = ["task", "lang", "lang_guess", "max_len", "head_max_len"]
- for fn, want in ((laya_predict, controls), (laya_shortlist, controls),
+ for fn, want in ((laya_predict, controls), (laya_shortlist, controls), (laya_tournament, controls),
(laya_preset, controls), (laya_route, ["model", "task", "lang", "lang_guess"])):
params = inspect.signature(fn).parameters
for name in want:
@@ -2099,7 +2099,7 @@ def test_controls_signature_and_schema():
repr(list(inspect.signature(laya_predict).parameters)))
by_name = {t.name: t for t in asyncio.run(mcp_server.list_tools())}
- for name, want in (("laya_predict", controls), ("laya_shortlist", controls),
+ for name, want in (("laya_predict", controls), ("laya_shortlist", controls), ("laya_tournament", controls),
("laya_preset", controls), ("laya_route", ["model", "task", "lang"])):
tool = by_name[name]
schema = tool.input_schema if hasattr(tool, "input_schema") else tool.inputSchema
@@ -2121,7 +2121,7 @@ def test_controls_signature_and_schema():
from laya.mcp import server as server_mod
model_schemas = []
- for name in ("laya_predict", "laya_shortlist", "laya_decide", "laya_route"):
+ for name in ("laya_predict", "laya_shortlist", "laya_tournament", "laya_decide", "laya_route"):
parameter = inspect.signature(getattr(server_mod, name + "_tool")).parameters["model"]
ok("signature/%s_model_default_none" % name, parameter.default is None, repr(parameter.default))
tool = by_name[name]
@@ -2882,9 +2882,9 @@ def test_server_registration():
names = sorted(t.name for t in tools)
ok("server/tool_names", names == ["laya_decide", "laya_predict", "laya_predict_batch",
"laya_preset", "laya_route", "laya_route_batch",
- "laya_shortlist", "laya_status"], repr(names))
+ "laya_shortlist", "laya_status", "laya_tournament"], repr(names))
decision = {"laya_predict", "laya_route", "laya_preset", "laya_shortlist",
- "laya_predict_batch", "laya_route_batch", "laya_decide"}
+ "laya_predict_batch", "laya_route_batch", "laya_decide", "laya_tournament"}
for t in tools:
desc = (t.description or "").lower()
ok("server/desc_%s_nonempty" % t.name, bool(desc.strip()), repr(desc))
@@ -2898,6 +2898,55 @@ def test_server_registration():
ok("server/desc_%s_requests" % t.name, "non-empty array" in desc)
+def test_server_tournament():
+ import json
+
+ from laya.mcp import server as server_mod
+ from mcp.server.mcpserver.exceptions import ToolError as McpToolError
+ import laya
+
+ by_name = {t.name: t for t in asyncio.run(mcp_server.list_tools())}
+ tool = by_name["laya_tournament"]
+ schema = tool.input_schema if hasattr(tool, "input_schema") else tool.inputSchema
+ props = schema["properties"]
+ default = inspect.signature(laya.predict_tournament).parameters["group_size"].default
+ ok("schema/tournament_group_default", props["group_size"]["default"] == default)
+ ok("schema/tournament_group_integer", props["group_size"]["type"] == "integer")
+ ok("schema/tournament_required", schema["required"] == ["state", "questions"])
+ for name in ("labels", "n", "rounds", "finalists", "option_order_dropped", "LAYA_BASE_URL"):
+ ok("schema/tournament_description_%s" % name, name in tool.description)
+
+ saved = server_mod._ROUTER
+ try:
+ router = TournamentRouter()
+ server_mod._ROUTER = router
+ result = asyncio.run(mcp_server.call_tool("laya_tournament", {
+ "state": STATE, "questions": tournament_questions(40), "group_size": 4,
+ "task": "typed_decisions", "lang_guess": "de", "lang": "fr",
+ "max_len": 1024, "head_max_len": 384, "min_confidence": 0.95,
+ }))
+ payload = json.loads(result.content[0].text)
+ ok("server/tournament_call_not_error", not result.is_error)
+ ok("server/tournament_custom_group", payload["tournament"]["intent"]["rounds"] == 2
+ and len(router.agent.calls) == 3)
+ ok("server/tournament_controls_reach_each_round",
+ all(k == {"model": "english", "lang": "fr", "max_len": 1024,
+ "head_max_len": 384, "min_confidence": 0.95}
+ for _s, _qs, k in router.agent.calls))
+ ok("server/tournament_route_controls", router.routes[0][2] == {
+ "task": "typed_decisions", "lang_guess": "de", "lang": "fr"})
+ ok("server/tournament_final_low_confidence", payload["answers"]["intent"]["low_confidence"])
+ try:
+ server_mod.laya_tournament_tool(STATE, tournament_questions(40), group_size=1)
+ except McpToolError as exc:
+ payload = json.loads(str(exc))
+ ok("server/tournament_error_payload", payload["error"] == "invalid_group_size")
+ else:
+ ok("server/tournament_error_payload", False, "invalid group_size accepted")
+ finally:
+ server_mod._ROUTER = saved
+
+
def test_server_shortlist_k_default():
"""The shortlist tool's advertised `k` default must be `laya.shortlist`'s.
@@ -3039,7 +3088,7 @@ def test_cli_mcp_page_tool_argument_rows():
return None
for tool in ("laya_status", "laya_route", "laya_predict",
- "laya_shortlist", "laya_preset", "laya_decide"):
+ "laya_shortlist", "laya_tournament", "laya_preset", "laya_decide"):
cell = row_cell(tool)
ok("docs-mcp/args_row_%s_present" % tool, cell is not None, "row not found")
if cell is None:
@@ -3096,6 +3145,7 @@ test_cli_mcp_page_batch_rows()
test_auto_task_env()
test_default_model_env()
test_server_registration()
+test_server_tournament()
test_server_shortlist_k_default()
test_cli_mcp_page_tool_argument_rows()
diff --git a/tests/test_mcp_local_e2e.py b/tests/test_mcp_local_e2e.py
index c5dce6e6..4fe8d02f 100644
--- a/tests/test_mcp_local_e2e.py
+++ b/tests/test_mcp_local_e2e.py
@@ -118,7 +118,7 @@ def main():
names = sorted(t["name"] for t in tools.get("tools", []))
ok("e2e/tool_names", names == ["laya_decide", "laya_predict", "laya_predict_batch",
"laya_preset", "laya_route", "laya_route_batch",
- "laya_shortlist", "laya_status"], repr(names))
+ "laya_shortlist", "laya_status", "laya_tournament"], repr(names))
ticket = {
"state": {