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): forward per-call prediction hooks to every runnable

Aashishbd777845198c
diff --git a/laya/integrations/langchain.py b/laya/integrations/langchain.py
index f7e5cb9b..a2223478 100644
--- a/laya/integrations/langchain.py
+++ b/laya/integrations/langchain.py
@@ -1,7 +1,8 @@
"""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.
+state evaluation nodes for LangChain Expression Language (LCEL) and LangGraph. Each
+runnable takes core's per-call prediction hooks.
Supports both local in-process models (`Agent` / `Router`) and remote HTTP
deployments (your own `laya-serve`) without requiring PyTorch on edge clients.
@@ -144,6 +145,35 @@ def _get_default_router():
return _DEFAULT_ROUTER
+def _reject_remote_hooks(hook_kwargs: Dict[str, Any], base_url: Optional[str]) -> None:
+ """Refuse hooks on a remote node rather than dropping them silently.
+
+ A hook is a Python callable that runs inside `predict` -- it can cache a decision, gate one or
+ rewrite its state. `laya-serve` has no way to receive or run one, so a node with a `base_url`
+ and hooks configured would report success while never calling them.
+ """
+ if base_url and hook_kwargs:
+ raise ValueError(
+ "%s run in the local runner and cannot be sent to a laya-serve endpoint; "
+ "install them where serve runs, or drop them" % ", ".join(sorted(hook_kwargs))
+ )
+
+
+def _hook_kwargs(hooks: Optional[Any] = None, on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None, hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None) -> Dict[str, Any]:
+ """The per-call hook overrides, with the unset ones omitted.
+
+ Core reads `None` as "inherit whatever the runner was built with", so an unset hook has to be
+ absent rather than passed as `None`. Note the `is not None` tests: `hooks=[]` means "no hooks
+ for this call", and `hooks_raise=False` means "keep deciding after a hook fails" -- both are
+ decisions a caller made, not absences.
+ """
+ given = {"hooks": hooks, "on_predict_start": on_predict_start, "on_predict_end": on_predict_end,
+ "hooks_raise": hooks_raise, "hooks_timeout": hooks_timeout}
+ return {k: v for k, v in given.items() if v is not None}
+
+
def _execute_decision(
state: Any,
questions: Dict[str, Any],
@@ -151,11 +181,19 @@ def _execute_decision(
base_url: Optional[str] = None,
api_key: Optional[str] = None,
model: Optional[str] = None,
+ hooks: Optional[Any] = None,
+ on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None,
+ hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None,
) -> Dict[str, Any]:
+ hook_kwargs = _hook_kwargs(hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout)
if base_url:
+ _reject_remote_hooks(hook_kwargs, base_url)
return _call_remote(base_url, state, questions, api_key=api_key, model=model)
runner = agent if agent is not None else _get_default_router()
kwargs = {"model": model} if model else {}
+ kwargs.update(hook_kwargs)
return runner.predict(state, questions, **kwargs)
@@ -175,6 +213,11 @@ class LayaRouter(RunnableSerializable):
base_url: Optional[str] = None
api_key: Optional[str] = None
model: Optional[str] = None
+ hooks: Optional[Any] = None
+ on_predict_start: Optional[Any] = None
+ on_predict_end: Optional[Any] = None
+ hooks_raise: Optional[bool] = None
+ hooks_timeout: Optional[float] = None
question_id: str = "route"
last_decision: Optional[Dict[str, Any]] = None
@@ -193,6 +236,11 @@ class LayaRouter(RunnableSerializable):
base_url: Optional[str] = None,
api_key: Optional[str] = None,
model: Optional[str] = None,
+ hooks: Optional[Any] = None,
+ on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None,
+ hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None,
**kwargs: Any,
):
if _RUNNABLE_AVAILABLE:
@@ -206,6 +254,11 @@ class LayaRouter(RunnableSerializable):
base_url=base_url,
api_key=api_key,
model=model,
+ hooks=hooks,
+ on_predict_start=on_predict_start,
+ on_predict_end=on_predict_end,
+ hooks_raise=hooks_raise,
+ hooks_timeout=hooks_timeout,
**kwargs,
)
else:
@@ -218,6 +271,11 @@ class LayaRouter(RunnableSerializable):
self.base_url = base_url
self.api_key = api_key
self.model = model
+ self.hooks = hooks
+ self.on_predict_start = on_predict_start
+ self.on_predict_end = on_predict_end
+ self.hooks_raise = hooks_raise
+ self.hooks_timeout = hooks_timeout
self.question_id = "route"
self.last_decision: Optional[Dict[str, Any]] = None
@@ -238,6 +296,11 @@ class LayaRouter(RunnableSerializable):
base_url=self.base_url,
api_key=self.api_key,
model=self.model,
+ hooks=self.hooks,
+ on_predict_start=self.on_predict_start,
+ on_predict_end=self.on_predict_end,
+ hooks_raise=self.hooks_raise,
+ hooks_timeout=self.hooks_timeout,
)
self.last_decision = res
ans = res["answers"][self.question_id]
@@ -271,6 +334,11 @@ class LayaGuardrail(RunnableSerializable):
base_url: Optional[str] = None
api_key: Optional[str] = None
model: Optional[str] = None
+ hooks: Optional[Any] = None
+ on_predict_start: Optional[Any] = None
+ on_predict_end: Optional[Any] = None
+ hooks_raise: Optional[bool] = None
+ hooks_timeout: Optional[float] = None
class Config:
arbitrary_types_allowed = True
@@ -287,6 +355,11 @@ class LayaGuardrail(RunnableSerializable):
base_url: Optional[str] = None,
api_key: Optional[str] = None,
model: Optional[str] = None,
+ hooks: Optional[Any] = None,
+ on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None,
+ hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None,
**kwargs: Any,
):
if _RUNNABLE_AVAILABLE:
@@ -300,6 +373,11 @@ class LayaGuardrail(RunnableSerializable):
base_url=base_url,
api_key=api_key,
model=model,
+ hooks=hooks,
+ on_predict_start=on_predict_start,
+ on_predict_end=on_predict_end,
+ hooks_raise=hooks_raise,
+ hooks_timeout=hooks_timeout,
**kwargs,
)
else:
@@ -312,6 +390,11 @@ class LayaGuardrail(RunnableSerializable):
self.base_url = base_url
self.api_key = api_key
self.model = model
+ self.hooks = hooks
+ self.on_predict_start = on_predict_start
+ self.on_predict_end = on_predict_end
+ self.hooks_raise = hooks_raise
+ self.hooks_timeout = hooks_timeout
def _default_questions(self) -> Dict[str, Any]:
from ..presets import guard_questions
@@ -329,6 +412,11 @@ class LayaGuardrail(RunnableSerializable):
base_url=self.base_url,
api_key=self.api_key,
model=self.model,
+ hooks=self.hooks,
+ on_predict_start=self.on_predict_start,
+ on_predict_end=self.on_predict_end,
+ hooks_raise=self.hooks_raise,
+ hooks_timeout=self.hooks_timeout,
)
answers = res.get("answers", {})
@@ -398,6 +486,11 @@ class LayaTriage(RunnableSerializable):
base_url: Optional[str] = None
api_key: Optional[str] = None
model: Optional[str] = None
+ hooks: Optional[Any] = None
+ on_predict_start: Optional[Any] = None
+ on_predict_end: Optional[Any] = None
+ hooks_raise: Optional[bool] = None
+ hooks_timeout: Optional[float] = None
class Config:
arbitrary_types_allowed = True
@@ -410,6 +503,11 @@ class LayaTriage(RunnableSerializable):
base_url: Optional[str] = None,
api_key: Optional[str] = None,
model: Optional[str] = None,
+ hooks: Optional[Any] = None,
+ on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None,
+ hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None,
**kwargs: Any,
):
if _RUNNABLE_AVAILABLE:
@@ -419,6 +517,11 @@ class LayaTriage(RunnableSerializable):
base_url=base_url,
api_key=api_key,
model=model,
+ hooks=hooks,
+ on_predict_start=on_predict_start,
+ on_predict_end=on_predict_end,
+ hooks_raise=hooks_raise,
+ hooks_timeout=hooks_timeout,
**kwargs,
)
else:
@@ -427,6 +530,11 @@ class LayaTriage(RunnableSerializable):
self.base_url = base_url
self.api_key = api_key
self.model = model
+ self.hooks = hooks
+ self.on_predict_start = on_predict_start
+ self.on_predict_end = on_predict_end
+ self.hooks_raise = hooks_raise
+ self.hooks_timeout = hooks_timeout
def invoke(self, state: Any, config: Optional[RunnableConfig] = None) -> Dict[str, Any]:
"""Triage the state and return enriched fields."""
@@ -440,6 +548,11 @@ class LayaTriage(RunnableSerializable):
base_url=self.base_url,
api_key=self.api_key,
model=self.model,
+ hooks=self.hooks,
+ on_predict_start=self.on_predict_start,
+ on_predict_end=self.on_predict_end,
+ hooks_raise=self.hooks_raise,
+ hooks_timeout=self.hooks_timeout,
)
ans = res.get("answers", {})
@@ -475,6 +588,11 @@ class LayaEvaluator(RunnableSerializable):
base_url: Optional[str] = None
api_key: Optional[str] = None
model: Optional[str] = None
+ hooks: Optional[Any] = None
+ on_predict_start: Optional[Any] = None
+ on_predict_end: Optional[Any] = None
+ hooks_raise: Optional[bool] = None
+ hooks_timeout: Optional[float] = None
class Config:
arbitrary_types_allowed = True
@@ -488,6 +606,11 @@ class LayaEvaluator(RunnableSerializable):
base_url: Optional[str] = None,
api_key: Optional[str] = None,
model: Optional[str] = None,
+ hooks: Optional[Any] = None,
+ on_predict_start: Optional[Any] = None,
+ on_predict_end: Optional[Any] = None,
+ hooks_raise: Optional[bool] = None,
+ hooks_timeout: Optional[float] = None,
**kwargs: Any,
):
if _RUNNABLE_AVAILABLE:
@@ -498,6 +621,11 @@ class LayaEvaluator(RunnableSerializable):
base_url=base_url,
api_key=api_key,
model=model,
+ hooks=hooks,
+ on_predict_start=on_predict_start,
+ on_predict_end=on_predict_end,
+ hooks_raise=hooks_raise,
+ hooks_timeout=hooks_timeout,
**kwargs,
)
else:
@@ -507,6 +635,11 @@ class LayaEvaluator(RunnableSerializable):
self.base_url = base_url
self.api_key = api_key
self.model = model
+ self.hooks = hooks
+ self.on_predict_start = on_predict_start
+ self.on_predict_end = on_predict_end
+ self.hooks_raise = hooks_raise
+ self.hooks_timeout = hooks_timeout
def evaluate_strings(self, *, prediction: str, input: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
"""LangChain standard string evaluation interface."""
@@ -518,6 +651,11 @@ class LayaEvaluator(RunnableSerializable):
base_url=self.base_url,
api_key=self.api_key,
model=self.model,
+ hooks=self.hooks,
+ on_predict_start=self.on_predict_start,
+ on_predict_end=self.on_predict_end,
+ hooks_raise=self.hooks_raise,
+ hooks_timeout=self.hooks_timeout,
)
return res.get("answers", {})
@@ -530,6 +668,11 @@ class LayaEvaluator(RunnableSerializable):
base_url=self.base_url,
api_key=self.api_key,
model=self.model,
+ hooks=self.hooks,
+ on_predict_start=self.on_predict_start,
+ on_predict_end=self.on_predict_end,
+ hooks_raise=self.hooks_raise,
+ hooks_timeout=self.hooks_timeout,
)
return res.get("answers", {})
diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py
index fa750e30..546d04e1 100644
--- a/tests/test_hooks_api.py
+++ b/tests/test_hooks_api.py
@@ -158,6 +158,31 @@ for label, cls in (("Agent", Agent), ("Router", Router), ("ONNXAgent", ONNXAgent
check_true("%s/%s exists" % (label, method), callable(getattr(cls, method, None)))
+# The LangChain runnables have to carry the per-call hook arguments too, or a chain cannot
+# install the cache/guard patterns from docs/hooks/patterns.md on a single node. They default to
+# None (meaning "inherit the runner"), which is what keeps an unset node byte-identical to today.
+# `hooks_concurrent` is deliberately absent: like the core predict surfaces, it is not per-call.
+from laya.integrations.langchain import ( # noqa: E402
+ LayaEvaluator,
+ LayaGuardrail,
+ LayaRouter,
+ LayaTriage,
+)
+
+PER_CALL_HOOK_PARAMS = ("hooks", "on_predict_start", "on_predict_end", "hooks_raise",
+ "hooks_timeout")
+
+for label, cls in (("LayaRouter", LayaRouter), ("LayaGuardrail", LayaGuardrail),
+ ("LayaTriage", LayaTriage), ("LayaEvaluator", LayaEvaluator)):
+ for param in PER_CALL_HOOK_PARAMS:
+ check_param("%s.__init__" % label, cls.__init__, param, None)
+ declared = getattr(cls, "model_fields", None)
+ if declared is not None:
+ check_true("%s/%s declared field" % (label, param), param in declared)
+ check_true("%s has no per-call hooks_concurrent" % label,
+ "hooks_concurrent" not in inspect.signature(cls.__init__).parameters)
+
+
print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
for f in FAIL:
print(" FAIL", f)
diff --git a/tests/test_langchain.py b/tests/test_langchain.py
index 628876c0..8779dbe2 100644
--- a/tests/test_langchain.py
+++ b/tests/test_langchain.py
@@ -272,6 +272,137 @@ check("evaluator/faithfulness", eval_res["faithfulness"]["noul"], 0.98)
check("evaluator/hallucination", eval_res["hallucination"]["noul"], 0.02)
+# --------------------------------------------------------------- 7. Prediction hooks
+from laya.integrations import langchain as langchain_module # noqa: E402
+from laya.hooks import PredictContext # noqa: E402
+
+
+class HookAgent:
+ """Answers every question with a fixed choice and records the keyword arguments it saw."""
+
+ def __init__(self, answer="billing"):
+ self.answer = answer
+ self.calls = []
+
+ def predict(self, state, questions, **kwargs):
+ self.calls.append(kwargs)
+ answers = {}
+ for qid, question in questions.items():
+ qtype = question.get("type")
+ if qtype == "choice":
+ answers[qid] = {"type": "choice", "choice": self.answer, "confidence": 0.9,
+ "probabilities": {}}
+ elif qtype == "score":
+ answers[qid] = {"type": "score", "score": 1.0, "confidence": 0.9,
+ "probabilities": {}}
+ else:
+ answers[qid] = {"type": "noul", "noul": 0.1, "confidence": 0.9}
+ return {"model": "mock", "answers": answers}
+
+
+HOOK_CRITERIA = {"billing": "invoices", "tech": "bugs"}
+HOOK_QUESTIONS = {"jailbreak": {"type": "noul", "instructions": "jailbreak?"}}
+HOOK_NODES = (
+ ("router", lambda a, **kw: LayaRouter(HOOK_CRITERIA, agent=a, **kw)),
+ ("guardrail", lambda a, **kw: LayaGuardrail(questions=HOOK_QUESTIONS, agent=a, **kw)),
+ ("triage", lambda a, **kw: LayaTriage(agent=a, **kw)),
+ ("evaluator", lambda a, **kw: LayaEvaluator(
+ questions={"faithful": {"type": "noul", "instructions": "faithful?"}}, agent=a, **kw)),
+)
+
+ALL_HOOK_KWARGS = {"hooks": ["H"], "on_predict_start": "S", "on_predict_end": "E",
+ "hooks_raise": True, "hooks_timeout": 0.5}
+
+for name, build in HOOK_NODES:
+ # Unset has to mean unsent: core reads a missing argument as "inherit the runner's own hooks",
+ # and passing None explicitly would say something different.
+ plain = HookAgent()
+ build(plain).invoke("some state")
+ check("hooks/%s default sends nothing" % name, plain.calls[0], {})
+
+ every = HookAgent()
+ build(every, **ALL_HOOK_KWARGS).invoke("some state")
+ check("hooks/%s forwards all five" % name, every.calls[0], ALL_HOOK_KWARGS)
+
+ # `hooks=[]` means "no hooks for this call" and `hooks_raise=False` means "keep deciding after
+ # a hook fails". Both are falsy and both are decisions, so neither may be dropped.
+ empty = HookAgent()
+ build(empty, hooks=[], hooks_raise=False).invoke("some state")
+ check("hooks/%s keeps falsy values" % name, empty.calls[0],
+ {"hooks": [], "hooks_raise": False})
+
+ model = HookAgent()
+ build(model, model="laya-multilingual", hooks=["H"]).invoke("some state")
+ check("hooks/%s alongside model" % name, model.calls[0],
+ {"model": "laya-multilingual", "hooks": ["H"]})
+
+# The node's whole job is to hand these arguments to `predict` unchanged, so every name it sends
+# has to be one the runners actually accept -- otherwise a chain fails with a TypeError deep inside
+# core instead of at the call site. Whether the hooks then run is core's contract, pinned by
+# tests/test_hooks.py; a mock runner that ignores its kwargs could not prove it either way.
+import inspect # noqa: E402
+from laya.agent import Agent # noqa: E402
+from laya.router import Router # noqa: E402
+
+agent_params = set(inspect.signature(Agent.system_one).parameters)
+router_params = set(inspect.signature(Router.predict).parameters)
+for param in ALL_HOOK_KWARGS:
+ check_true("hooks/%s is an Agent.predict parameter" % param, param in agent_params)
+ check_true("hooks/%s is a Router.predict parameter" % param, param in router_params)
+
+class Watcher:
+ """A minimal lifecycle hook; only its identity matters to the node under test."""
+
+ def on_predict_start(self, ctx):
+ pass
+
+ def on_predict_end(self, ctx):
+ pass
+
+
+# Identity, not equality: the node must hand `predict` the caller's own hook objects, so a hook
+# that keys state off `self` still works after the trip through the runnable.
+sentinel_hooks = [Watcher()]
+identity_agent = HookAgent()
+LayaRouter(HOOK_CRITERIA, agent=identity_agent, hooks=sentinel_hooks).invoke("x")
+check_true("hooks/forwards the caller's objects",
+ identity_agent.calls[0]["hooks"] is sentinel_hooks
+ and identity_agent.calls[0]["hooks"][0] is sentinel_hooks[0])
+
+
+# Hooks are Python callables that run inside predict(); a remote node cannot carry them, and
+# silently dropping them would report success for a cache or a guard that never ran.
+remote_hook_calls = []
+_real_call_remote = langchain_module._call_remote
+
+
+def hook_spy_call_remote(base_url, state, questions, api_key=None, model=None):
+ remote_hook_calls.append(1)
+ return {"answers": {"route": {"type": "choice", "choice": "billing", "confidence": 0.9}}}
+
+
+langchain_module._call_remote = hook_spy_call_remote
+try:
+ remote_plain = LayaRouter(HOOK_CRITERIA, base_url="http://laya:8000", api_key="k")
+ check("hooks/remote without hooks still routes", remote_plain.invoke("x"), "billing")
+ # One sample value per parameter, of the type that parameter declares: an ill-typed value
+ # would be rejected by the runnable's own schema and never reach the guard under test.
+ for param, sample in (("hooks", [Watcher()]), ("on_predict_start", Watcher().on_predict_start),
+ ("on_predict_end", Watcher().on_predict_end),
+ ("hooks_raise", False), ("hooks_timeout", 0.5)):
+ raised, message = False, ""
+ try:
+ LayaRouter(HOOK_CRITERIA, base_url="http://laya:8000", **{param: sample}).invoke("x")
+ except ValueError as e:
+ raised, message = True, str(e)
+ check_true("hooks/remote refuses %s" % param, raised)
+ check_true("hooks/remote %s names itself" % param, param in message)
+ check_true("hooks/remote %s names the endpoint" % param, "laya-serve" in message)
+ check("hooks/remote made no extra call", len(remote_hook_calls), 1)
+finally:
+ langchain_module._call_remote = _real_call_remote
+
+
# --------------------------------------------------------------- Summary
print(f"PASS: {len(PASS)}")
print(f"FAIL: {len(FAIL)}")