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): add laya_decide, the schema-driven decision tool

Aashish931490db0491
diff --git a/laya/mcp/server.py b/laya/mcp/server.py
index 77debc0f..277e9439 100644
--- a/laya/mcp/server.py
+++ b/laya/mcp/server.py
@@ -39,6 +39,7 @@ from laya.serve import _apply_thread_limit, _env_bool
from .device import env_device
from .tools import (
ToolError,
+ laya_decide,
laya_predict,
laya_predict_batch,
laya_preset,
@@ -292,6 +293,25 @@ def laya_preset_tool(preset: str, state: dict) -> str:
)
+ name="laya_decide",
+ description=(
+ "Answer a JSON-schema-shaped decision in one forward pass and return the decided "
+ "values: schema is a JSON schema object whose properties are enum choices, booleans "
+ "(noul), or integers with integer minimum/maximum (ordinal score); free strings, "
+ "arrays and nested objects are rejected by path. Use this instead of laya_predict "
+ "when the caller already knows the answer shape and wants values projected onto the "
+ "schema (enum member, integer level, boolean) plus per-field confidence, instead of "
+ "an answer map to parse by hand. "
+ + _GUARDRAILS
+ ),
+)
+def laya_decide_tool(state: dict, schema: dict, model: str = "auto") -> str:
+ """Answer a JSON-schema-shaped decision and return the decided values."""
+ router = _router_or_error()
+ return _wrap(laya_decide, state=state, schema=schema, model=model, router=router)
+
+
def main() -> None:
# Windows without Developer Mode cannot create HF cache symlinks (WinError
# 1314). On POSIX the cache uses symlinks by default and disabling them
diff --git a/laya/mcp/tools.py b/laya/mcp/tools.py
index ca117b90..2f4c3ad0 100644
--- a/laya/mcp/tools.py
+++ b/laya/mcp/tools.py
@@ -543,3 +543,64 @@ def laya_route_batch(requests: Any, *, router: Any = None) -> dict:
key = name if isinstance(name, str) and name else "unknown"
model_counts[key] = model_counts.get(key, 0) + 1
return {"decisions": out, "model_counts": model_counts}
+
+
+def laya_decide(
+ state: Any,
+ schema: Any,
+ model: Any = "auto",
+ *,
+ router: Any = None,
+ agent: Any = None,
+) -> dict:
+ """Answer a JSON-schema-shaped decision and return the decided values.
+
+ The MCP form of ``laya.decide`` (the schema-driven API: an object of enum /
+ bounded-integer / boolean properties is turned into Laya questions, answered
+ in one forward pass, and projected back onto the schema). MCP clients carry
+ JSON, not pydantic classes, so ``schema`` is a JSON schema dictionary. The
+ answer is ``values`` -- enum members, integer levels, booleans -- beside the
+ per-field ``confidence``/``probabilities`` and the usual routing/device/
+ latency metadata, so a client never parses an answer map by hand.
+ """
+ # Lazy: keeps laya.structured (pure Python, but a module import is still a
+ # module import) out of this module's import-time surface.
+ from laya.structured import SchemaError, decide
+
+ state_d = validate_state(state)
+ model_name = validate_model(model)
+ try:
+ # `decide` validates the schema itself (SchemaError names the offending
+ # path) and projects the answers; calling it with return_details keeps
+ # this tool on the core's exact semantics instead of a copied projection.
+ started = time.perf_counter()
+ if model_name == "auto":
+ if router is None:
+ raise ToolError("models_not_ready", "Router is not loaded (auto mode)")
+ details = decide(router, state_d, schema=schema, return_details=True)
+ elif agent is not None:
+ details = decide(agent, state_d, schema=schema, return_details=True)
+ else:
+ if router is None:
+ raise ToolError("models_not_ready", "no agent/router loaded")
+ details = decide(router, state_d, schema=schema, return_details=True,
+ model=model_name)
+ except SchemaError as exc:
+ raise ToolError("invalid_schema", str(exc)) from exc
+ latency_ms = (time.perf_counter() - started) * 1000.0
+
+ answers = _normalize_answers(details.answers)
+ routing = details.routing or {"model": model_name, "repo": None, "reason": "explicit model"}
+ device = _reading_device(router, agent, model_name, details.routing)
+ out: dict[str, Any] = {
+ "values": details.values,
+ "confidence": details.confidence,
+ "probabilities": details.probabilities,
+ "routing": routing,
+ "latency_ms": round(latency_ms, 3),
+ }
+ if details.usage:
+ out["usage"] = details.usage
+ if device:
+ out["device"] = device
+ return out
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index d0a97512..c68ba531 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -29,6 +29,7 @@ from laya.mcp.device import agent_device, device_report, env_device, resolve_dev
from laya.mcp.server import _models_from_env, server as mcp_server # noqa: E402
from laya.mcp.tools import ( # noqa: E402
ToolError,
+ laya_decide,
laya_predict,
laya_predict_batch,
laya_preset,
@@ -670,6 +671,110 @@ def test_batch_route():
"internal_error")
+# --- decide tool (mocked router, no weights) ----------------------------------
+
+DECIDE_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "department": {"enum": ["billing", "support", "sales"],
+ "description": "Which team should handle this ticket?"},
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ },
+}
+
+
+class TypeEchoRouter(FakeRouter):
+ """FakeRouter that also answers with the real payload shape: the `type`
+ key and a probabilities dict keyed by option/level, like system_one does,
+ so laya.structured's per-field probabilities are exercised."""
+
+ def predict(self, state, questions, **kwargs):
+ out = super().predict(state, questions, **kwargs)
+ for name, spec in questions.items():
+ answer = out["answers"][name]
+ answer["type"] = spec["type"]
+ if spec["type"] == "score":
+ answer["probabilities"] = {"0": 0.1, "1": 0.2, "2": 0.7}
+ return out
+
+
+def test_decide():
+ import laya
+
+ router = TypeEchoRouter()
+ out = laya_decide(STATE, DECIDE_SCHEMA, router=router)
+ ok("decide/keys", set(out) >= {"values", "confidence", "probabilities", "routing", "latency_ms"},
+ repr(sorted(out)))
+ ok("decide/values_choice", out["values"]["department"] == "billing", repr(out["values"]))
+ ok("decide/values_score_level", out["values"]["urgency"] == 2, repr(out["values"]))
+ ok("decide/values_bool", out["values"]["needs_human"] is True, repr(out["values"]))
+ ok("decide/confidence", set(out["confidence"]) == {"department", "urgency", "needs_human"}
+ and out["confidence"]["department"] == 0.94, repr(out["confidence"]))
+ ok("decide/probs_noul_pair", set(out["probabilities"]["needs_human"]) == {"false", "true"}
+ and out["probabilities"]["needs_human"]["true"] == 0.892,
+ repr(out["probabilities"]["needs_human"]))
+ ok("decide/probs_score_offset", set(out["probabilities"]["urgency"]) >= {"0", "1", "2"},
+ repr(out["probabilities"]["urgency"]))
+ ok("decide/score_level_from_probs", out["values"]["urgency"] == 2, repr(out["values"]))
+ ok("decide/device", out.get("device") == "cpu", repr(out.get("device")))
+ ok("decide/routing", out["routing"]["model"] == "english")
+
+ # Same values the core decide() returns for the same runner: the tool is a
+ # thin MCP surface over the documented schema projection, not a second one.
+ core = laya.decide(router, STATE, schema=DECIDE_SCHEMA)
+ ok("decide/parity_with_core", out["values"] == core, "tool=%r core=%r" % (out["values"], core))
+
+ # Score projection follows the argmax of the distribution, offset by minimum.
+ class LowUrgencyRouter(TypeEchoRouter):
+ def predict(self, state, questions, **kwargs):
+ out = super().predict(state, questions, **kwargs)
+ out["answers"]["urgency"] = {"type": "score", "score": 2.0, "confidence": 0.6,
+ "probabilities": {"0": 0.6, "1": 0.3, "2": 0.1}}
+ return out
+
+ out = laya_decide(STATE, DECIDE_SCHEMA, router=LowUrgencyRouter())
+ ok("decide/score_argmax", out["values"]["urgency"] == 0, repr(out["values"]["urgency"]))
+
+ expect_tool_error("decide/bad_state", lambda: laya_decide({}, DECIDE_SCHEMA, router=router),
+ "invalid_state")
+ for bad, why in (({"type": "object"}, "no properties"),
+ ({"type": "object", "properties": {"x": {"type": "string"}}}, "free string"),
+ ({"type": "object", "properties": {"x": {"type": "array"}}}, "array"),
+ ({}, "empty"), ([], "not an object")):
+ expect_tool_error("decide/bad_schema_%s" % why,
+ lambda b=bad: laya_decide(STATE, b, router=router), "invalid_schema")
+ expect_tool_error("decide/bad_model",
+ lambda: laya_decide(STATE, DECIDE_SCHEMA, model="gpt4", router=router),
+ "invalid_model")
+ expect_tool_error("decide/no_router",
+ lambda: laya_decide(STATE, DECIDE_SCHEMA), "models_not_ready")
+ # Explicit model with a direct agent: answered by the agent, no Router needed.
+ # A bare Agent payload carries no routing, which is when the tool synthesises
+ # the "explicit model" routing entry (laya_predict does the same).
+ class BareAgent:
+ device = "cpu"
+
+ def predict(self, state, questions, **kwargs):
+ answers = {}
+ for name, spec in questions.items():
+ if spec["type"] == "choice":
+ answers[name] = {"type": "choice", "choice": "billing", "confidence": 0.9,
+ "probabilities": {"billing": 0.9, "support": 0.1}}
+ elif spec["type"] == "score":
+ answers[name] = {"type": "score", "score": 1.0, "confidence": 0.6,
+ "probabilities": {"0": 0.2, "1": 0.6, "2": 0.2}}
+ else:
+ answers[name] = {"type": "noul", "noul": 0.2, "confidence": 0.8}
+ return {"answers": answers}
+
+ out = laya_decide(STATE, DECIDE_SCHEMA, model="english", agent=BareAgent())
+ ok("decide/direct_agent", out["values"]["department"] == "billing"
+ and out["routing"] == {"model": "english", "repo": None, "reason": "explicit model"},
+ repr(out["routing"]))
+ ok("decide/direct_agent_device", out.get("device") == "cpu", repr(out.get("device")))
+
+
def test_timeout_removed():
# The per-call timeout was removed: a ThreadPoolExecutor shutdown waits for
# the work anyway, and MCP clients apply their own request timeout. The tool
@@ -679,7 +784,7 @@ def test_timeout_removed():
import laya.mcp.tools as tools_mod
for fn in (laya_predict, laya_route, laya_preset, laya_shortlist,
- laya_predict_batch, laya_route_batch):
+ laya_predict_batch, laya_route_batch, laya_decide):
ok("timeout/param_absent_%s" % fn.__name__, "timeout" not in inspect.signature(fn).parameters)
ok("timeout/executor_absent", "ThreadPoolExecutor" not in inspect.getsource(tools_mod))
@@ -709,11 +814,11 @@ def test_models_from_env():
def test_server_registration():
tools = asyncio.run(mcp_server.list_tools())
names = sorted(t.name for t in tools)
- ok("server/tool_names", names == ["laya_predict", "laya_predict_batch", "laya_preset",
- "laya_route", "laya_route_batch", "laya_shortlist",
- "laya_status"], repr(names))
+ 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))
decision = {"laya_predict", "laya_route", "laya_preset", "laya_shortlist",
- "laya_predict_batch", "laya_route_batch"}
+ "laya_predict_batch", "laya_route_batch", "laya_decide"}
for t in tools:
desc = (t.description or "").lower()
ok("server/desc_%s_nonempty" % t.name, bool(desc.strip()), repr(desc))
@@ -737,6 +842,7 @@ test_shortlist()
test_batch_validation()
test_batch_predict()
test_batch_route()
+test_decide()
test_timeout_removed()
test_models_from_env()
test_server_registration()
diff --git a/tests/test_mcp_local_e2e.py b/tests/test_mcp_local_e2e.py
index cb62643a..1fc67eed 100644
--- a/tests/test_mcp_local_e2e.py
+++ b/tests/test_mcp_local_e2e.py
@@ -2,7 +2,7 @@
Launches ``python -m laya.mcp.server`` as a subprocess and speaks MCP over
stdin/stdout (newline-delimited JSON-RPC), exactly like a real MCP client.
-Exercises laya_predict, laya_predict_batch, laya_route, laya_route_batch,
+Exercises laya_predict, laya_predict_batch, laya_route, laya_route_batch, laya_decide,
laya_preset, laya_shortlist and laya_status against the
live checkpoints (downloaded via huggingface_hub on first run, cached
afterwards).
@@ -116,9 +116,9 @@ def main():
tools = client.request("tools/list", {})
names = sorted(t["name"] for t in tools.get("tools", []))
- ok("e2e/tool_names", names == ["laya_predict", "laya_predict_batch", "laya_preset",
- "laya_route", "laya_route_batch", "laya_shortlist",
- "laya_status"], repr(names))
+ 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))
ticket = {
"state": {
@@ -207,6 +207,49 @@ def main():
and all(d.get("model") in ("english", "multilingual", "typed-decisions") and d.get("reason")
for d in decisions), repr(decisions))
+ # laya_decide: the same ticket as a JSON-schema decision. The
+ # projected enum must equal laya_predict's choice above -- the tool
+ # translates schema -> questions -> values, it must not move the
+ # decision -- and a rejected schema must come back as a readable
+ # invalid_schema payload, not a crash.
+ decide_arguments = {
+ "state": ticket["state"],
+ "schema": {
+ "type": "object",
+ "properties": {
+ "department": {
+ "enum": ["billing", "technical"],
+ "description": "Which team should handle this ticket?",
+ },
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ },
+ },
+ }
+ result = client.request("tools/call", {"name": "laya_decide",
+ "arguments": decide_arguments})
+ payload = json.loads(result["content"][0]["text"])
+ ok("e2e/decide_not_error", not result.get("isError"), repr(result.get("isError")))
+ values = payload.get("values") or {}
+ ok("e2e/decide_value_parity", values.get("department") == ans["choice"],
+ "predict=%r decide=%r" % (ans.get("choice"), values.get("department")))
+ ok("e2e/decide_value_types", isinstance(values.get("urgency"), int)
+ and 0 <= values["urgency"] <= 2
+ and isinstance(values.get("needs_human"), bool), repr(values))
+ ok("e2e/decide_confidence", 0.0 < payload.get("confidence", {}).get("department", -1) <= 1.0,
+ repr(payload.get("confidence")))
+ result = client.request("tools/call", {"name": "laya_decide", "arguments": {
+ "state": ticket["state"],
+ "schema": {"type": "object", "properties": {"summary": {"type": "string"}}},
+ }})
+ # mcp 2.x prefixes a raised McpToolError's text with
+ # "Error executing tool <name>: "; the JSON payload starts at the
+ # first brace, so parse from there either way.
+ text = result["content"][0]["text"]
+ payload = json.loads(text[text.index("{"):])
+ ok("e2e/decide_bad_schema", result.get("isError") and payload.get("error") == "invalid_schema"
+ and "properties.summary" in payload.get("message", ""), repr(payload))
+
result = client.request("tools/call", {"name": "laya_route", "arguments": ticket})
payload = json.loads(result["content"][0]["text"])
ok("e2e/route_model", payload.get("model") in ("english", "multilingual", "typed-decisions"), repr(payload))