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(langchain): add LayaDecision, the schema-driven decision node

Aashish8de84997d121
diff --git a/laya/__init__.py b/laya/__init__.py
index b6462e54..f6382e85 100644
--- a/laya/__init__.py
+++ b/laya/__init__.py
@@ -40,6 +40,7 @@ _LAZY_ATTRS = {
"LayaGuardrailError": (".integrations", "LayaGuardrailError"),
"LayaTriage": (".integrations", "LayaTriage"),
"LayaEvaluator": (".integrations", "LayaEvaluator"),
+ "LayaDecision": (".integrations", "LayaDecision"),
}
@@ -93,6 +94,7 @@ __all__ = [
"LayaGuardrailError",
"LayaTriage",
"LayaEvaluator",
+ "LayaDecision",
"PredictContext",
"PredictHook",
"Hook",
diff --git a/laya/integrations/__init__.py b/laya/integrations/__init__.py
index 7ce62e40..32815956 100644
--- a/laya/integrations/__init__.py
+++ b/laya/integrations/__init__.py
@@ -1,5 +1,6 @@
"""Third-party agent and framework integrations for Laya."""
from .langchain import (
+ LayaDecision,
LayaEvaluator,
LayaGuardrail,
LayaGuardrailError,
@@ -13,4 +14,5 @@ __all__ = [
"LayaGuardrailError",
"LayaTriage",
"LayaEvaluator",
+ "LayaDecision",
]
diff --git a/laya/integrations/langchain.py b/laya/integrations/langchain.py
index f7e5cb9b..e36866fd 100644
--- a/laya/integrations/langchain.py
+++ b/laya/integrations/langchain.py
@@ -1,7 +1,7 @@
"""LangChain and LangGraph integration for Laya System 1 decision engine.
-Provides fast (~33 ms), non-autoregressive routing, real-time guardrails, and
-state evaluation nodes for LangChain Expression Language (LCEL) and LangGraph.
+Provides fast (~33 ms), non-autoregressive routing, real-time guardrails, schema-driven
+decisions and state evaluation nodes for LangChain Expression Language (LCEL) and LangGraph.
Supports both local in-process models (`Agent` / `Router`) and remote HTTP
deployments (your own `laya-serve`) without requiring PyTorch on edge clients.
@@ -535,3 +535,106 @@ class LayaEvaluator(RunnableSerializable):
def __call__(self, state: Any) -> Dict[str, Any]:
return self.invoke(state)
+
+
+def _validate_decision_schema(schema: Any) -> None:
+ """Plan ``schema`` into Laya questions and keep only the errors it raises."""
+ from ..structured import questions_from_json_schema, questions_from_pydantic
+
+ if hasattr(schema, "model_json_schema") or hasattr(schema, "schema"):
+ questions_from_pydantic(schema)
+ else:
+ questions_from_json_schema(schema)
+
+
+class _RemoteDecisionRunner:
+ """Present a remote ``laya-serve`` endpoint with the ``predict`` API ``laya.decide`` drives.
+
+ The HTTP endpoint answers a question set exactly as a local runner does, so wrapping it lets
+ remote mode share core's schema projection instead of reimplementing it here.
+ """
+
+ def __init__(self, base_url: str, api_key: Optional[str] = None):
+ self.base_url = base_url
+ self.api_key = api_key
+
+ def predict(self, state: Any, questions: Dict[str, Any], model: Optional[str] = None) -> Dict[str, Any]:
+ return _call_remote(self.base_url, state, questions, api_key=self.api_key, model=model)
+
+
+class LayaDecision(RunnableSerializable):
+ """Schema-driven decision node: a JSON schema or pydantic model in, schema-shaped values out.
+
+ This is the LCEL form of `laya.decide`, so a chain or graph node gets a typed decision -- an
+ enum choice, an integer level, a boolean -- from one forward pass, without writing the Laya
+ questions by hand and without a structured-output parser downstream.
+
+ The schema is planned at construction: a property Laya cannot answer from a fixed option set
+ (a free string, an array, a nested object) raises `SchemaError` here rather than on the first
+ request, after the chain has already paid for every earlier step.
+ """
+
+ decision_schema: Any
+ return_details: bool = False
+ state_key: Optional[Union[str, Callable[[Any], Any]]] = None
+ agent: Optional[Any] = None
+ base_url: Optional[str] = None
+ api_key: Optional[str] = None
+ model: Optional[str] = None
+
+ class Config:
+ arbitrary_types_allowed = True
+ extra = "allow"
+
+ def __init__(
+ self,
+ decision_schema: Any,
+ return_details: bool = False,
+ state_key: Optional[Union[str, Callable[[Any], Any]]] = None,
+ agent: Optional[Any] = None,
+ base_url: Optional[str] = None,
+ api_key: Optional[str] = None,
+ model: Optional[str] = None,
+ **kwargs: Any,
+ ):
+ _validate_decision_schema(decision_schema)
+ if _RUNNABLE_AVAILABLE:
+ super().__init__(
+ decision_schema=decision_schema,
+ return_details=return_details,
+ state_key=state_key,
+ agent=agent,
+ base_url=base_url,
+ api_key=api_key,
+ model=model,
+ **kwargs,
+ )
+ else:
+ self.decision_schema = decision_schema
+ self.return_details = return_details
+ self.state_key = state_key
+ self.agent = agent
+ self.base_url = base_url
+ self.api_key = api_key
+ self.model = model
+
+ def invoke(self, input: Any, config: Optional[RunnableConfig] = None) -> Any:
+ """Decide ``input`` against the schema and return its values, or a ``DecisionResult``."""
+ from ..structured import decide
+
+ text = _extract_text(input, self.state_key)
+ if self.base_url:
+ runner: Any = _RemoteDecisionRunner(self.base_url, self.api_key)
+ else:
+ runner = self.agent if self.agent is not None else _get_default_router()
+ kwargs = {"model": self.model} if self.model else {}
+ return decide(
+ runner,
+ text,
+ schema=self.decision_schema,
+ return_details=self.return_details,
+ **kwargs,
+ )
+
+ def __call__(self, state: Any) -> Any:
+ return self.invoke(state)
diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py
index fa750e30..5736ebbd 100644
--- a/tests/test_hooks_api.py
+++ b/tests/test_hooks_api.py
@@ -157,6 +157,23 @@ for label, cls in (("Agent", Agent), ("Router", Router), ("ONNXAgent", ONNXAgent
for method in ("add_hook", "remove_hook", "hooks_installed"):
check_true("%s/%s exists" % (label, method), callable(getattr(cls, method, None)))
+# --------------------------------------------------------------- LangChain decision node
+# `LayaDecision` is the LCEL form of `laya.decide`, so its constructor has to keep accepting the
+# same schema argument and runner overrides. The module imports without langchain-core installed
+# (the runnable base falls back to plain object), so these checks hold in every CI lane.
+from laya.integrations.langchain import LayaDecision # noqa: E402
+
+for param, default in (("return_details", False), ("state_key", None), ("agent", None),
+ ("base_url", None), ("api_key", None), ("model", None)):
+ check_param("LayaDecision.__init__", LayaDecision.__init__, param, default)
+check_param("LayaDecision.__init__", LayaDecision.__init__, "decision_schema",
+ inspect.Parameter.empty, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+check_true("LayaDecision/invoke exists", callable(getattr(LayaDecision, "invoke", None)))
+check_true("LayaDecision/__all__", "LayaDecision" in laya.__all__)
+check_true("LayaDecision/laya attribute", hasattr(laya, "LayaDecision"))
+check_true("LayaDecision/integrations export",
+ "LayaDecision" in __import__("laya.integrations", fromlist=["__all__"]).__all__)
+
print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
for f in FAIL:
diff --git a/tests/test_langchain.py b/tests/test_langchain.py
index 628876c0..467ebe76 100644
--- a/tests/test_langchain.py
+++ b/tests/test_langchain.py
@@ -1,7 +1,8 @@
"""Unit tests for Laya LangChain and LangGraph integration.
Tests verify routing logic, confidence threshold fallback gating, guardrail filtering/raising,
-state extraction, and LangGraph callable conventions without requiring model downloads or GPU.
+state extraction, schema-driven decisions, and LangGraph callable conventions without requiring
+model downloads or GPU.
"""
import os
import sys
@@ -272,6 +273,175 @@ check("evaluator/faithfulness", eval_res["faithfulness"]["noul"], 0.98)
check("evaluator/hallucination", eval_res["hallucination"]["noul"], 0.02)
+# --------------------------------------------------------------- 6. LayaDecision
+from laya.integrations import langchain as langchain_module # noqa: E402
+from laya.integrations.langchain import LayaDecision # noqa: E402
+from laya.structured import DecisionResult, SchemaError, decide # noqa: E402
+
+DECISION_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "department": {"type": "string", "enum": ["billing", "support", "sales"]},
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ },
+}
+
+DECISION_ANSWERS = {
+ "department": {"type": "choice", "choice": "billing", "confidence": 0.9,
+ "probabilities": {"billing": 0.9, "support": 0.1, "sales": 0.0}},
+ "urgency": {"type": "score", "score": 1.2, "confidence": 0.6,
+ "probabilities": {"0": 0.1, "1": 0.2, "2": 0.7}},
+ "needs_human": {"type": "noul", "noul": 0.8, "confidence": 0.75},
+}
+
+
+class RecordingAgent:
+ """Answers every question set with DECISION_ANSWERS and records each predict() call."""
+
+ def __init__(self, answers=None):
+ self.answers = DECISION_ANSWERS if answers is None else answers
+ self.calls = []
+
+ def predict(self, state, questions, **kwargs):
+ self.calls.append({"state": state, "questions": questions, "kwargs": kwargs})
+ return {"model": "mock", "answers": dict(self.answers),
+ "usage": {"input_tokens": 1, "output_tokens": 0}}
+
+
+decision_agent = RecordingAgent()
+decision = LayaDecision(DECISION_SCHEMA, agent=decision_agent)
+
+values = decision.invoke({"input": "I was billed twice, is anyone going to help?"})
+check("decision/choice keeps its schema value", values["department"], "billing")
+check("decision/score becomes the argmax level", values["urgency"], 2)
+check("decision/boolean is a bool", values["needs_human"], True)
+
+# Every property of the schema reaches the agent as a Laya question of the right kind.
+asked = decision_agent.calls[0]["questions"]
+check("decision/one question per property", sorted(asked), ["department", "needs_human", "urgency"])
+check("decision/enum planned as choice", asked["department"]["type"], "choice")
+check("decision/enum labels", list(asked["department"]["criteria"]), ["billing", "support", "sales"])
+check("decision/boolean planned as noul", asked["needs_human"]["type"], "noul")
+check("decision/state extracted", decision_agent.calls[0]["state"],
+ "I was billed twice, is anyone going to help?")
+
+# The runnable is `laya.decide` over the same runner: byte-identical output is the contract.
+check("decision/parity with laya.decide", decision.invoke("some text"),
+ decide(decision_agent, "some text", schema=DECISION_SCHEMA))
+
+details = LayaDecision(DECISION_SCHEMA, return_details=True, agent=RecordingAgent()).invoke("x")
+check_true("decision/details type", isinstance(details, DecisionResult))
+check("decision/details confidence", details.confidence["urgency"], 0.6)
+check("decision/details usage", details.usage, {"input_tokens": 1, "output_tokens": 0})
+
+# model= and the extra predict kwargs go through to the runner, as core does.
+kw_agent = RecordingAgent()
+LayaDecision(DECISION_SCHEMA, agent=kw_agent, model="laya-multilingual").invoke("x")
+check("decision/model forwarded", kw_agent.calls[0]["kwargs"], {"model": "laya-multilingual"})
+
+# A property the engine did not answer is absent, not guessed.
+partial = LayaDecision(DECISION_SCHEMA, agent=RecordingAgent({"department": DECISION_ANSWERS["department"]})).invoke("x")
+check("decision/unanswered property omitted", partial, {"department": "billing"})
+
+# A schema Laya cannot answer fails here, not on the first request through the chain.
+for label, bad in (
+ ("free string", {"type": "object", "properties": {"a": {"type": "string"}}}),
+ ("no properties", {"type": "object", "properties": {}}),
+ ("not a schema", "billing|support"),
+):
+ raised = False
+ try:
+ LayaDecision(bad, agent=decision_agent)
+ except SchemaError:
+ raised = True
+ check_true("decision/rejects %s at construction" % label, raised)
+
+# Remote mode goes through the same projection with one HTTP call per input.
+remote_calls = []
+
+
+def fake_call_remote(base_url, state, questions, api_key=None, model=None):
+ remote_calls.append({"base_url": base_url, "state": state, "questions": questions,
+ "api_key": api_key, "model": model})
+ return {"model": "mock", "answers": dict(DECISION_ANSWERS)}
+
+
+_real_call_remote = langchain_module._call_remote
+langchain_module._call_remote = fake_call_remote
+try:
+ remote_decision = LayaDecision(DECISION_SCHEMA, base_url="http://laya:8000", api_key="k", model="laya")
+ check("decision/remote values", remote_decision.invoke({"query": "billed twice"}), values)
+ check("decision/remote one call", len(remote_calls), 1)
+ check("decision/remote endpoint", remote_calls[0]["base_url"], "http://laya:8000")
+ check("decision/remote credentials", remote_calls[0]["api_key"], "k")
+ check("decision/remote model", remote_calls[0]["model"], "laya")
+ check("decision/remote questions", sorted(remote_calls[0]["questions"]),
+ ["department", "needs_human", "urgency"])
+finally:
+ langchain_module._call_remote = _real_call_remote
+
+# With no agent and no base_url the node uses the shared default Router, like its siblings.
+default_agent = RecordingAgent()
+_real_default_router = langchain_module._get_default_router
+langchain_module._get_default_router = lambda: default_agent
+try:
+ check("decision/default runner", LayaDecision(DECISION_SCHEMA).invoke("x"), values)
+ check("decision/default runner used once", len(default_agent.calls), 1)
+finally:
+ langchain_module._get_default_router = _real_default_router
+
+# A pydantic model is a schema too, so the same class can type a chain and a call site. Note
+# `Literal[0, 1, 2]` plans as an enum choice rather than a score scale, so the answer carries a
+# label and the value comes back as the schema's own int.
+try:
+ from typing import Literal
+
+ import pydantic
+
+ class Ticket(pydantic.BaseModel):
+ department: Literal["billing", "support", "sales"]
+ urgency: Literal[0, 1, 2]
+ needs_human: bool
+
+ ticket_agent = RecordingAgent({
+ "department": DECISION_ANSWERS["department"],
+ "urgency": {"type": "choice", "choice": "2", "confidence": 0.6,
+ "probabilities": {"0": 0.1, "1": 0.2, "2": 0.7}},
+ "needs_human": DECISION_ANSWERS["needs_human"],
+ })
+ model_decision = LayaDecision(Ticket, agent=ticket_agent)
+ check("decision/pydantic values", model_decision.invoke("billed twice"),
+ {"department": "billing", "urgency": 2, "needs_human": True})
+ check_true("decision/pydantic integer enum stays an int",
+ isinstance(model_decision.invoke("billed twice")["urgency"], int))
+ check("decision/pydantic parity",
+ model_decision.invoke("y"), decide(ticket_agent, "y", schema=Ticket))
+except ImportError:
+ PASS.append("decision/pydantic skipped (not installed)")
+
+# Composes with the rest of LCEL: a decision feeds a downstream step as plain values.
+try:
+ from langchain_core.runnables import RunnableLambda
+
+ decide_then_label = LayaDecision(DECISION_SCHEMA, agent=RecordingAgent()) | RunnableLambda(
+ lambda v: "%s/%s" % (v["department"], v["urgency"])
+ )
+ check("decision/lcel chain", decide_then_label.invoke({"input": "billed twice"}), "billing/2")
+ check("decision/lcel batch", LayaDecision(DECISION_SCHEMA, agent=RecordingAgent()).batch(
+ [{"input": "a"}, {"input": "b"}], config={"max_concurrency": 1}), [values, values])
+except ImportError:
+ PASS.append("decision/lcel skipped (langchain-core not installed)")
+
+# Exported from the package the way the other integration nodes are.
+import laya # noqa: E402
+from laya.integrations import __all__ as integrations_all # noqa: E402
+
+check("decision/laya attribute", laya.LayaDecision, LayaDecision)
+check_true("decision/in laya.__all__", "LayaDecision" in laya.__all__)
+check_true("decision/in integrations.__all__", "LayaDecision" in integrations_all)
+
+
# --------------------------------------------------------------- Summary
print(f"PASS: {len(PASS)}")
print(f"FAIL: {len(FAIL)}")