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(structured): schema-driven decisions via decide() (#280)

Emiliano G.O.a5f3514fcdf9
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bd62feeb..c731c99f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -84,6 +84,8 @@ jobs:
python tests/test_batch.py
python tests/test_hooks.py
python tests/test_hooks_api.py
+ python tests/test_structured.py
+ python tests/test_structured_api.py
python tests/test_download.py
python tests/test_shortlist.py
python tests/test_decision_model.py
diff --git a/README.md b/README.md
index c86ef176..f5d36fce 100644
--- a/README.md
+++ b/README.md
@@ -548,6 +548,34 @@ state/questions or `ctx.skip(...)` a cached answer; an end hook can rewrite the
---
+## Schema-driven decisions
+
+Describe the shape you want with a JSON schema or a pydantic model, and Laya answers it in one
+forward pass, with typed values and calibrated confidence.
+
+```python
+import laya
+
+schema = {
+ "type": "object",
+ "properties": {
+ "department": {"type": "string", "enum": ["billing", "support", "sales"],
+ "description": "Which team should handle this?"},
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ },
+}
+
+agent = laya.load("convaiinnovations/laya")
+agent.decide("I was charged twice, refund me.", schema=schema)
+# {"department": "billing", "urgency": 2, "needs_human": True}
+```
+
+`decide` also works on a `Router`, accepts a pydantic model (install `laya[structured]`), and can
+return per-field confidence with `return_details=True`. See [`docs/structured.md`](docs/structured.md).
+
+---
+
## Built-in Workflow Presets
Laya provides pre-tuned question schemas for immediate production use:
diff --git a/docs/structured.md b/docs/structured.md
new file mode 100644
index 00000000..a2bd0c10
--- /dev/null
+++ b/docs/structured.md
@@ -0,0 +1,126 @@
+# Schema-driven decisions
+
+Turn a JSON schema, or a pydantic model, into Laya questions, and get back typed values with
+calibrated confidence. This is the bridge that makes Laya a structured-output engine: you describe
+the shape you want, Laya answers it in one forward pass.
+
+```python
+import laya
+
+schema = {
+ "type": "object",
+ "properties": {
+ "department": {"type": "string", "enum": ["billing", "support", "sales"],
+ "description": "Which team should handle this?"},
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ },
+}
+
+agent = laya.load("convaiinnovations/laya")
+values = agent.decide("I was charged twice, refund me.", schema=schema)
+# {"department": "billing", "urgency": 2, "needs_human": True}
+```
+
+With pydantic (install `laya[structured]`):
+
+```python
+from typing import Literal
+from pydantic import BaseModel
+
+class Ticket(BaseModel):
+ department: Literal["billing", "support", "sales"]
+ urgency: Literal[0, 1, 2]
+ needs_human: bool
+
+ticket = agent.decide("I was charged twice, refund me.", schema=Ticket)
+```
+
+## The supported subset
+
+The top level must be an object with `properties`. Each property becomes one question.
+
+| JSON schema | Laya question | Returned value |
+|---|---|---|
+| `enum`, `Literal`, `const` | `choice` | the chosen value, with its original type |
+| `boolean` | `noul` | `true` / `false` |
+| `integer` or `number` with `minimum` and `maximum`, span up to `MAX_SCORE_LEVELS` | `score` | the highest-probability level, as an integer |
+| `string` with `enum` | `choice` | the chosen string |
+| `description` | question instructions | |
+| `title` | option label | |
+
+Projection is exact: an `enum: [1, 2, 3]` returns `2`, not `"2"`; a bounded integer returns a
+level between `minimum` and `maximum`; a boolean is `noul >= 0.5`.
+
+## Rejections
+
+A schema that cannot be answered from a fixed option set raises `laya.structured.SchemaError`
+(a `ValueError`) naming the exact path:
+
+| case | message shape |
+|---|---|
+| free `string` without `enum` | `properties.name: a free string cannot be a fixed option set; use 'enum' or a boolean` |
+| `array` | `properties.name: arrays are not supported; ask one field per element` |
+| nested `object` | `properties.name: nested objects are not supported; flatten the schema` |
+| `$ref` / recursion | `properties.name: $ref/recursion is not supported; flatten the schema` |
+| unbounded number | `properties.name: a numeric field needs integer 'minimum' and 'maximum' to become a score` |
+| more than `MAX_PROPERTIES` / `MAX_OPTIONS` / `MAX_SCORE_LEVELS` | the limit is named in the message |
+
+Limits: `MAX_PROPERTIES = 32`, `MAX_OPTIONS = 32`, `MAX_SCORE_LEVELS = 10`.
+
+## The API
+
+| function | purpose |
+|---|---|
+| `laya.decide(runner, state, schema=..., *, questions=..., return_details=..., **predict_kwargs)` | the free function, works for `Agent` and `Router` |
+| `agent.decide(state, schema=..., ...)` / `router.decide(state, schema=..., ...)` | convenience methods |
+| `questions_from_json_schema(schema)` | schema to Laya questions |
+| `questions_from_pydantic(model)` | pydantic model to questions (requires pydantic) |
+| `answers_to_json(answers, schema)` | project raw answers onto schema values |
+| `answer_to_pydantic(model, answers)` | project raw answers into a pydantic instance |
+| `plan_from_json_schema(schema)` | the validated field plan (advanced) |
+
+Pass exactly one of `schema` or `questions`. With `questions`, `decide` returns the raw answers
+instead of projecting. Extra keyword arguments are forwarded to `predict`, so hooks, `model=`,
+`task=` and the token budget all work:
+
+```python
+router.decide(state, schema=Ticket, model="multilingual", hooks=[Metrics()])
+```
+
+## Confidence and probabilities
+
+By default `decide` returns only the values. Pass `return_details=True` for a `DecisionResult`
+with per-field confidence, probabilities, the raw answers, and the usage and routing of the call:
+
+```python
+result = agent.decide(state, schema=Ticket, return_details=True)
+result.values["department"] # "billing"
+result.confidence["department"] # 0.94
+result.probabilities["department"] # {"billing": 0.94, "support": 0.06, "sales": 0.0}
+result.usage # {"input_tokens": 42, "output_tokens": 0}
+result.routing # the Router decision, when a Router answered
+```
+
+You can gate on it, for example escalate a field whose confidence is below a threshold:
+
+```python
+if result.confidence["department"] < 0.6:
+ result.values["department"] = "human-review"
+```
+
+## How it maps internally
+
+- Enum and `Literal` become `choice` questions with the values as string labels; the label is
+ mapped back to the original value on the way out, so integers stay integers.
+- A bounded integer becomes a `score` question with one level per value; the returned value is
+ `minimum + argmax`.
+- A boolean becomes a `noul` question; the value is `noul >= 0.5`.
+- A `description` becomes the question instructions, so a good description is what makes the
+ decision accurate. This follows the same rule as the [hooks guide](hooks/index.md): be explicit
+ about what each option means.
+
+## See also
+
+- [Prediction hooks](hooks/index.md): observe, shape, cache or gate the decisions this produces.
+- [Decision primitives](index.md): `choice`, `score` and `noul` in depth.
diff --git a/laya/__init__.py b/laya/__init__.py
index facc843d..f061cda3 100644
--- a/laya/__init__.py
+++ b/laya/__init__.py
@@ -12,6 +12,7 @@ from .presets import (
triage_questions,
)
from .router import DEFAULT_MODELS, RouteDecision, Router
+from .structured import DecisionResult, decide
__version__ = "0.3.11"
@@ -92,5 +93,7 @@ __all__ = [
"PredictHook",
"Hook",
"BaseHook",
+ "decide",
+ "DecisionResult",
"__version__",
]
diff --git a/laya/agent.py b/laya/agent.py
index 41b205b6..285885ce 100644
--- a/laya/agent.py
+++ b/laya/agent.py
@@ -865,6 +865,18 @@ class Agent(HookRegistry):
pass
return False
+ def decide(self, state: Union[str, dict, list], schema: Any = None, *,
+ questions: Optional[Dict[str, Any]] = None, return_details: bool = False,
+ **predict_kwargs) -> Any:
+ """Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
+
+ See `laya.structured`. Pass exactly one of `schema` or `questions`; extra keyword arguments
+ are forwarded to `predict` / `system_one`.
+ """
+ from .structured import decide as _decide
+ return _decide(self, state, schema, questions=questions,
+ return_details=return_details, **predict_kwargs)
+
predict = system_one
diff --git a/laya/onnx_agent.py b/laya/onnx_agent.py
index 8d363df7..58e3ff2c 100644
--- a/laya/onnx_agent.py
+++ b/laya/onnx_agent.py
@@ -279,4 +279,16 @@ class ONNXAgent(HookRegistry):
"usage": {"input_tokens": n_tokens, "output_tokens": 0},
}
+ def decide(self, state: Union[str, dict, list], schema: Any = None, *,
+ questions: Optional[Dict[str, Dict[str, Any]]] = None, return_details: bool = False,
+ **predict_kwargs) -> Any:
+ """Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
+
+ See `laya.structured`. Pass exactly one of `schema` or `questions`; extra keyword arguments
+ are forwarded to `predict` / `system_one`.
+ """
+ from laya.structured import decide as _decide
+ return _decide(self, state, schema, questions=questions,
+ return_details=return_details, **predict_kwargs)
+
predict = system_one
diff --git a/laya/router.py b/laya/router.py
index ccbe5980..6becc646 100644
--- a/laya/router.py
+++ b/laya/router.py
@@ -582,6 +582,18 @@ class Router(HookRegistry):
raise
return ctx.results[0]
+ def decide(self, state: Union[str, dict, list], schema: Any = None, *,
+ questions: Optional[Dict[str, Any]] = None, return_details: bool = False,
+ **predict_kwargs) -> Any:
+ """Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
+
+ See `laya.structured`. Pass exactly one of `schema` or `questions`; extra keyword arguments
+ (for example `model=`, `task=`, `hooks=`) are forwarded to `predict`.
+ """
+ from .structured import decide as _decide
+ return _decide(self, state, schema, questions=questions,
+ return_details=return_details, **predict_kwargs)
+
def __enter__(self):
return self
diff --git a/laya/structured.py b/laya/structured.py
new file mode 100644
index 00000000..5bb226cf
--- /dev/null
+++ b/laya/structured.py
@@ -0,0 +1,260 @@
+"""Schema-driven decisions: turn a JSON schema (or a pydantic model) into Laya questions.
+
+Pure Python and torch-free, so `import laya` stays light. The mapping is a documented subset:
+an object of properties, each an enum choice, a boolean, or a bounded integer scale. Anything
+that cannot be answered from a fixed option set (free strings, arrays, nested objects) is
+rejected with an error that names the path.
+
+ import laya
+
+ class Ticket(BaseModel):
+ department: Literal["billing", "support", "sales"]
+ urgency: Literal[0, 1, 2]
+ needs_human: bool
+
+ values = laya.decide(agent, state, schema=Ticket)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+MAX_PROPERTIES = 32
+MAX_OPTIONS = 32
+MAX_SCORE_LEVELS = 10
+
+
+class SchemaError(ValueError):
+ """A schema cannot be expressed as Laya questions; the message names the path."""
+
+
+@dataclass
+class DecisionResult:
+ """The detailed result of `decide(..., return_details=True)`.
+
+ `values` is the schema-shaped output. `confidence` and `probabilities` are keyed by field,
+ and `answers` is Laya's raw answer per field.
+ """
+
+ values: Dict[str, Any]
+ confidence: Dict[str, float]
+ probabilities: Dict[str, Dict[str, Any]]
+ answers: Dict[str, Any]
+ usage: Optional[Dict[str, int]] = None
+ routing: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class _Field:
+ name: str
+ kind: str # "choice" | "score" | "noul"
+ question: Dict[str, Any]
+ options: List[Tuple[str, Any]] = field(default_factory=list) # choice: (label, value)
+ minimum: Optional[int] = None # score: level 0 value
+
+
+def _require_pydantic():
+ try:
+ import pydantic # noqa: F401
+ except ImportError as exc: # pragma: no cover - depends on the environment
+ raise ImportError(
+ "pydantic is required for the typed-model helpers; install 'laya[structured]'"
+ ) from exc
+
+
+def _schema_of(model: Any) -> Dict[str, Any]:
+ if hasattr(model, "model_json_schema"): # pydantic v2
+ return model.model_json_schema()
+ if hasattr(model, "schema"): # pydantic v1
+ return model.schema()
+ if isinstance(model, dict):
+ return model
+ raise SchemaError("expected a JSON schema dict or a pydantic model, got %s" % type(model).__name__)
+
+
+def _enum_field(path: str, name: str, values: Sequence[Any], description: Optional[str]) -> _Field:
+ if len(values) > MAX_OPTIONS:
+ raise SchemaError("%s: %d options exceeds MAX_OPTIONS=%d" % (path, len(values), MAX_OPTIONS))
+ if not values:
+ raise SchemaError("%s: 'enum' must not be empty" % path)
+ if all(isinstance(v, bool) for v in values):
+ return _noul_field(path, name, description)
+ options = [(("null" if v is None else str(v)), v) for v in values]
+ criteria = {label: None for label, _ in options}
+ question = {
+ "type": "choice",
+ "instructions": description or ("What is `%s`?" % name),
+ "criteria": criteria,
+ }
+ return _Field(name=name, kind="choice", question=question, options=options)
+
+
+def _noul_field(path: str, name: str, description: Optional[str]) -> _Field:
+ question = {
+ "type": "noul",
+ "instructions": description or ("Is `%s` true?" % name),
+ }
+ return _Field(name=name, kind="noul", question=question)
+
+
+def _score_field(path: str, name: str, prop: Dict[str, Any],
+ description: Optional[str]) -> _Field:
+ lo, hi = prop.get("minimum"), prop.get("maximum")
+ if not isinstance(lo, int) or not isinstance(hi, int):
+ raise SchemaError(
+ "%s: a numeric field needs integer 'minimum' and 'maximum' to become a score" % path)
+ if hi < lo:
+ raise SchemaError("%s: 'maximum' %d is below 'minimum' %d" % (path, hi, lo))
+ span = hi - lo + 1
+ if span > MAX_SCORE_LEVELS:
+ raise SchemaError(
+ "%s: %d levels exceeds MAX_SCORE_LEVELS=%d; narrow the range or use an enum"
+ % (path, span, MAX_SCORE_LEVELS))
+ question = {
+ "type": "score",
+ "instructions": description or ("Score `%s` from %d to %d" % (name, lo, hi)),
+ "criteria": [str(v) for v in range(lo, hi + 1)],
+ }
+ return _Field(name=name, kind="score", question=question, minimum=lo)
+
+
+def _field(path: str, name: str, prop: Dict[str, Any]) -> _Field:
+ if not isinstance(prop, dict):
+ raise SchemaError("%s: property must be an object, got %s" % (path, type(prop).__name__))
+ description = prop.get("description")
+ if "const" in prop:
+ return _enum_field(path, name, [prop["const"]], description)
+ if "enum" in prop:
+ return _enum_field(path, name, prop["enum"], description)
+
+ jtype = prop.get("type")
+ if isinstance(jtype, list): # nullable: ["string", "null"]
+ jtype = next((t for t in jtype if t != "null"), None)
+ if jtype == "boolean":
+ return _noul_field(path, name, description)
+ if jtype == "string":
+ raise SchemaError(
+ "%s: a free string cannot be a fixed option set; use 'enum' or a boolean" % path)
+ if jtype in ("integer", "number"):
+ return _score_field(path, name, prop, description)
+ if jtype == "array":
+ raise SchemaError("%s: arrays are not supported; ask one field per element" % path)
+ if jtype == "object":
+ raise SchemaError("%s: nested objects are not supported; flatten the schema" % path)
+ if "$ref" in prop:
+ raise SchemaError("%s: $ref/recursion is not supported; flatten the schema" % path)
+ raise SchemaError("%s: unsupported schema %r" % (path, prop))
+
+
+def plan_from_json_schema(schema: Dict[str, Any]) -> List[_Field]:
+ """Validate a JSON schema and return one planned field per property."""
+ if not isinstance(schema, dict):
+ raise SchemaError("expected a JSON schema object, got %s" % type(schema).__name__)
+ if schema.get("type") not in (None, "object") or "properties" not in schema:
+ raise SchemaError("the top level must be an object with 'properties'")
+ properties = schema["properties"]
+ if not isinstance(properties, dict) or not properties:
+ raise SchemaError("'properties' must be a non-empty object")
+ if len(properties) > MAX_PROPERTIES:
+ raise SchemaError("%d properties exceeds MAX_PROPERTIES=%d" % (len(properties), MAX_PROPERTIES))
+ return [_field("properties.%s" % name, name, prop) for name, prop in properties.items()]
+
+
+def questions_from_json_schema(schema: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
+ """Turn a JSON schema into Laya questions (a documented subset; see the module docstring)."""
+ return {f.name: f.question for f in plan_from_json_schema(schema)}
+
+
+def questions_from_pydantic(model: Any) -> Dict[str, Dict[str, Any]]:
+ """Turn a pydantic model into Laya questions. Requires pydantic (the `structured` extra)."""
+ _require_pydantic()
+ return questions_from_json_schema(_schema_of(model))
+
+
+def _project(answers: Dict[str, Any], fields: Sequence[_Field]) -> Dict[str, Any]:
+ values: Dict[str, Any] = {}
+ for f in fields:
+ answer = answers.get(f.name)
+ if answer is None:
+ continue
+ if f.kind == "noul":
+ values[f.name] = bool(float(answer.get("noul", 0.0)) >= 0.5)
+ elif f.kind == "score":
+ probs = answer.get("probabilities") or {}
+ if probs:
+ idx = max(range(len(probs)), key=lambda i: float(probs.get(str(i), probs.get(i, 0.0))))
+ else:
+ idx = int(round(float(answer.get("score", 0.0)))) - int(f.minimum or 0)
+ values[f.name] = int(f.minimum or 0) + idx
+ else: # choice
+ label = str(answer.get("choice"))
+ values[f.name] = next((value for lbl, value in f.options if lbl == label), label)
+ return values
+
+
+def answers_to_json(answers: Dict[str, Any], schema: Dict[str, Any]) -> Dict[str, Any]:
+ """Project Laya answers onto the schema values (choice value, integer level, boolean)."""
+ return _project(answers, plan_from_json_schema(schema))
+
+
+def answer_to_pydantic(model: Any, answers: Dict[str, Any]) -> Any:
+ """Project Laya answers into a pydantic model instance. Requires pydantic."""
+ _require_pydantic()
+ return model(**answers_to_json(answers, _schema_of(model)))
+
+
+def _details(values: Dict[str, Any], answers: Dict[str, Any], result: Dict[str, Any]) -> DecisionResult:
+ confidence: Dict[str, float] = {}
+ probabilities: Dict[str, Dict[str, Any]] = {}
+ for name, answer in answers.items():
+ confidence[name] = float(answer.get("confidence", 0.0))
+ if answer.get("type") == "noul":
+ p = float(answer.get("noul", 0.0))
+ probabilities[name] = {"false": round(1.0 - p, 4), "true": round(p, 4)}
+ else:
+ probabilities[name] = dict(answer.get("probabilities") or {})
+ return DecisionResult(
+ values=values,
+ confidence=confidence,
+ probabilities=probabilities,
+ answers=dict(answers),
+ usage=result.get("usage"),
+ routing=result.get("routing"),
+ )
+
+
+def decide(runner, state: Any, schema: Any = None, *, questions: Optional[Dict[str, Any]] = None,
+ return_details: bool = False, **predict_kwargs) -> Any:
+ """Answer `state` against a schema (or explicit questions) and return the decided values.
+
+ Pass exactly one of `schema` or `questions`. With `schema`, the values follow the schema
+ (choice values, integer levels, booleans). With `questions`, the raw answers are returned.
+ `return_details=True` returns a `DecisionResult` instead of the plain values. Extra keyword
+ arguments are forwarded to `runner.predict`.
+ """
+ if (schema is None) == (questions is None):
+ raise ValueError("pass exactly one of schema= or questions=")
+
+ fields: Optional[List[_Field]] = None
+ if schema is not None:
+ fields = plan_from_json_schema(_schema_of(schema))
+ questions = {f.name: f.question for f in fields}
+
+ result = runner.predict(state, questions, **predict_kwargs)
+ answers = result.get("answers", {}) or {}
+ values = _project(answers, fields) if fields is not None else dict(answers)
+ if return_details:
+ return _details(values, answers, result)
+ return values
+
+
+__all__ = [
+ "DecisionResult",
+ "SchemaError",
+ "answers_to_json",
+ "answer_to_pydantic",
+ "decide",
+ "plan_from_json_schema",
+ "questions_from_json_schema",
+ "questions_from_pydantic",
+]
diff --git a/tests/test_structured.py b/tests/test_structured.py
new file mode 100644
index 00000000..5ab3ac8e
--- /dev/null
+++ b/tests/test_structured.py
@@ -0,0 +1,202 @@
+"""Schema-driven decisions: mapping, projection and rejections. No model, no download.
+
+Run: python tests/test_structured.py
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import laya # noqa: E402
+from laya.structured import ( # noqa: E402
+ SchemaError,
+ answers_to_json,
+ answer_to_pydantic,
+ decide,
+ plan_from_json_schema,
+ questions_from_json_schema,
+ questions_from_pydantic,
+)
+
+PASS, FAIL = [], []
+
+
+def check(name, got, want):
+ if got == want:
+ PASS.append(name)
+ else:
+ FAIL.append("%s: got %r, want %r" % (name, got, want))
+
+
+def check_true(name, cond):
+ if cond:
+ PASS.append(name)
+ else:
+ FAIL.append(name)
+
+
+def check_raises(name, exc, fn):
+ try:
+ fn()
+ except exc:
+ PASS.append(name)
+ return
+ except BaseException as other: # noqa: BLE001
+ FAIL.append("%s: raised %r, want %r" % (name, other, exc))
+ return
+ FAIL.append("%s: did not raise %r" % (name, exc))
+
+
+SCHEMA = {
+ "type": "object",
+ "properties": {
+ "department": {"type": "string", "enum": ["billing", "support", "sales"],
+ "description": "Which team?"},
+ "urgency": {"type": "integer", "minimum": 0, "maximum": 2},
+ "needs_human": {"type": "boolean"},
+ "priority": {"enum": [1, 2, 3]},
+ },
+}
+
+
+# --------------------------------------------------------------- mapping
+questions = questions_from_json_schema(SCHEMA)
+check("map/enum is a choice", questions["department"]["type"], "choice")
+check("map/description becomes instructions", questions["department"]["instructions"], "Which team?")
+check("map/enum labels", list(questions["department"]["criteria"]), ["billing", "support", "sales"])
+check("map/bounded number is a score", questions["urgency"]["type"], "score")
+check("map/score levels", questions["urgency"]["criteria"], ["0", "1", "2"])
+check("map/boolean is noul", questions["needs_human"]["type"], "noul")
+check("map/integer enum becomes a choice", questions["priority"]["type"], "choice")
+check("map/integer enum labels are strings", list(questions["priority"]["criteria"]), ["1", "2", "3"])
+check("map/plan has one field per property", len(plan_from_json_schema(SCHEMA)), 4)
+
+
+# --------------------------------------------------------------- projection
+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.5,
+ "probabilities": {"0": 0.1, "1": 0.2, "2": 0.7}, "legend": {}},
+ "needs_human": {"type": "noul", "noul": 0.8, "confidence": 0.8},
+ "priority": {"type": "choice", "choice": "2", "confidence": 0.7,
+ "probabilities": {"1": 0.2, "2": 0.7, "3": 0.1}},
+}
+values = answers_to_json(ANSWERS, SCHEMA)
+check("project/choice value", values["department"], "billing")
+check("project/score is the argmax level", values["urgency"], 2)
+check("project/noul is a bool", values["needs_human"], True)
+check("project/integer enum keeps its type", values["priority"], 2)
+check_true("project/integer enum is an int", isinstance(values["priority"], int))
+check("project/false noul",
+ answers_to_json({"x": {"type": "noul", "noul": 0.2}},
+ {"type": "object", "properties": {"x": {"type": "boolean"}}})["x"],
+ False)
+
+
+# --------------------------------------------------------------- rejections
+def _bad(schema):
+ return lambda: questions_from_json_schema(schema)
+
+
+check_raises("reject/free string", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "string"}}}))
+check_raises("reject/array", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "array", "items": {"type": "string"}}}}))
+check_raises("reject/nested object", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "object", "properties": {}}}}))
+check_raises("reject/$ref", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"$ref": "#/$defs/X"}}}))
+check_raises("reject/unbounded number", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "integer", "minimum": 0}}}))
+check_raises("reject/score too wide", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "integer", "minimum": 0, "maximum": 100}}}))
+check_raises("reject/too many properties", SchemaError,
+ _bad({"type": "object", "properties": {("p%d" % i): {"type": "boolean"} for i in range(33)}}))
+check_raises("reject/too many options", SchemaError,
+ _bad({"type": "object", "properties": {"a": {"type": "string", "enum": ["v%d" % i for i in range(33)]}}}))
+check_raises("reject/non-object root", SchemaError, _bad({"type": "array"}))
+check_raises("reject/empty properties", SchemaError, _bad({"type": "object", "properties": {}}))
+
+
+# --------------------------------------------------------------- decide
+class FakeRunner:
+ def __init__(self, answers):
+ self.answers = answers
+ self.calls = []
+
+ def predict(self, state, questions, **kwargs):
+ self.calls.append({"state": state, "questions": questions, "kwargs": kwargs})
+ return {"answers": self.answers, "usage": {"input_tokens": 1, "output_tokens": 0},
+ "routing": {"model": "english"}}
+
+
+runner = FakeRunner(ANSWERS)
+out = decide(runner, "some state", schema=SCHEMA)
+check("decide/values", out["department"], "billing")
+check("decide/builds questions", runner.calls[0]["questions"]["department"]["type"], "choice")
+check("decide/forwards state", runner.calls[0]["state"], "some state")
+
+details = decide(runner, "some state", schema=SCHEMA, return_details=True)
+check("decide/details confidence", details.confidence["department"], 0.9)
+check("decide/details noul probabilities", details.probabilities["needs_human"], {"false": 0.2, "true": 0.8})
+check("decide/details usage", details.usage, {"input_tokens": 1, "output_tokens": 0})
+check("decide/details routing", details.routing, {"model": "english"})
+
+runner = FakeRunner({"a": {"type": "noul", "noul": 0.9, "confidence": 0.9}})
+out = decide(runner, "s", questions={"a": {"type": "noul", "instructions": "?"}})
+check("decide/questions pass-through returns answers", out,
+ {"a": {"type": "noul", "noul": 0.9, "confidence": 0.9}})
+
+check_raises("decide/requires schema or questions", ValueError, lambda: decide(runner, "s"))
+check_raises("decide/rejects both", ValueError, lambda: decide(runner, "s", schema=SCHEMA, questions={}))
+
+# kwargs are forwarded to predict
+runner = FakeRunner(ANSWERS)
+decide(runner, "s", schema=SCHEMA, hooks_raise=False)
+check("decide/forwards predict kwargs", runner.calls[0]["kwargs"], {"hooks_raise": False})
+
+
+# --------------------------------------------------------------- pydantic (optional)
+try:
+ from typing import Literal
+
+ import pydantic
+
+ class Ticket(pydantic.BaseModel):
+ department: Literal["billing", "support", "sales"]
+ urgency: Literal[0, 1, 2]
+ needs_human: bool
+
+ pq = questions_from_pydantic(Ticket)
+ check("pydantic/choice", pq["department"]["type"], "choice")
+ check("pydantic/int literal choice", pq["urgency"]["type"], "choice")
+ check("pydantic/bool noul", pq["needs_human"]["type"], "noul")
+
+ ticket = answer_to_pydantic(Ticket, {
+ "department": {"type": "choice", "choice": "support", "confidence": 0.9, "probabilities": {}},
+ "urgency": {"type": "choice", "choice": "1", "confidence": 0.6, "probabilities": {}},
+ "needs_human": {"type": "noul", "noul": 0.7, "confidence": 0.7},
+ })
+ check("pydantic/instance", (ticket.department, ticket.urgency, ticket.needs_human),
+ ("support", 1, True))
+except ImportError:
+ PASS.append("pydantic/skipped (not installed)")
+
+
+# --------------------------------------------------------------- exports and methods
+check("export/decide", callable(laya.decide), True)
+check("export/DecisionResult", hasattr(laya, "DecisionResult"), True)
+check("method/Agent.decide", callable(getattr(laya.Agent, "decide", None)), True)
+check("method/Router.decide", callable(getattr(laya.Router, "decide", None)), True)
+from laya.onnx_agent import ONNXAgent # noqa: E402
+
+check("method/ONNXAgent.decide", callable(getattr(ONNXAgent, "decide", None)), True)
+
+
+print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
+for f in FAIL:
+ print(" FAIL", f)
+if not FAIL:
+ print("all structured tests passed")
+sys.exit(1 if FAIL else 0)
diff --git a/tests/test_structured_api.py b/tests/test_structured_api.py
new file mode 100644
index 00000000..16d67b02
--- /dev/null
+++ b/tests/test_structured_api.py
@@ -0,0 +1,108 @@
+"""API-stability guard for schema-driven decisions.
+
+Pins the public signatures, constants, the DecisionResult fields and the exports, so a change
+that would break callers fails here first. Update this file in the same commit as an intentional
+change.
+
+Run: python tests/test_structured_api.py
+"""
+import dataclasses
+import inspect
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import laya # noqa: E402
+from laya import structured # noqa: E402
+
+PASS, FAIL = [], []
+
+
+def check(name, got, want):
+ if got == want:
+ PASS.append(name)
+ else:
+ FAIL.append("%s: got %r, want %r" % (name, got, want))
+
+
+def check_true(name, cond, detail=""):
+ if cond:
+ PASS.append(name)
+ else:
+ FAIL.append("%s%s" % (name, ": " + detail if detail else ""))
+
+
+def check_param(name, fn, param, default):
+ params = inspect.signature(fn).parameters
+ if param not in params:
+ FAIL.append("%s/%s: missing parameter" % (name, param))
+ return
+ check("%s/%s default" % (name, param), params[param].default, default)
+
+
+def check_kwonly(name, fn, param):
+ params = inspect.signature(fn).parameters
+ if param not in params:
+ FAIL.append("%s/%s: missing parameter" % (name, param))
+ return
+ check("%s/%s kind" % (name, param), params[param].kind, inspect.Parameter.KEYWORD_ONLY)
+
+
+# --------------------------------------------------------------- constants
+check("MAX_PROPERTIES", structured.MAX_PROPERTIES, 32)
+check("MAX_OPTIONS", structured.MAX_OPTIONS, 32)
+check("MAX_SCORE_LEVELS", structured.MAX_SCORE_LEVELS, 10)
+
+# --------------------------------------------------------------- functions
+check_param("questions_from_json_schema", structured.questions_from_json_schema, "schema", inspect.Parameter.empty)
+check_param("questions_from_pydantic", structured.questions_from_pydantic, "model", inspect.Parameter.empty)
+check_param("answers_to_json", structured.answers_to_json, "answers", inspect.Parameter.empty)
+check_param("answers_to_json", structured.answers_to_json, "schema", inspect.Parameter.empty)
+check_param("answer_to_pydantic", structured.answer_to_pydantic, "model", inspect.Parameter.empty)
+check_param("answer_to_pydantic", structured.answer_to_pydantic, "answers", inspect.Parameter.empty)
+check_param("plan_from_json_schema", structured.plan_from_json_schema, "schema", inspect.Parameter.empty)
+
+check_param("decide", structured.decide, "runner", inspect.Parameter.empty)
+check_param("decide", structured.decide, "state", inspect.Parameter.empty)
+check_param("decide", structured.decide, "schema", None)
+check_kwonly("decide", structured.decide, "questions")
+check_kwonly("decide", structured.decide, "return_details")
+check_param("decide", structured.decide, "questions", None)
+check_param("decide", structured.decide, "return_details", False)
+check_true("decide/accepts **predict_kwargs",
+ any(p.kind == inspect.Parameter.VAR_KEYWORD for p in inspect.signature(structured.decide).parameters.values()))
+
+# --------------------------------------------------------------- DecisionResult
+FIELDS = ["values", "confidence", "probabilities", "answers", "usage", "routing"]
+check("DecisionResult fields", [f.name for f in dataclasses.fields(structured.DecisionResult)], FIELDS)
+for optional in ("usage", "routing"):
+ check("DecisionResult/%s default None" % optional,
+ structured.DecisionResult.__dataclass_fields__[optional].default, None)
+
+# --------------------------------------------------------------- methods
+for label, cls in (("Agent", laya.Agent), ("Router", laya.Router)):
+ fn = getattr(cls, "decide", None)
+ check_true("%s.decide exists" % label, callable(fn))
+ if fn is not None:
+ check_param("%s.decide" % label, fn, "schema", None)
+ check_kwonly("%s.decide" % label, fn, "questions")
+ check_kwonly("%s.decide" % label, fn, "return_details")
+
+from laya.onnx_agent import ONNXAgent # noqa: E402
+
+check_true("ONNXAgent.decide exists", callable(getattr(ONNXAgent, "decide", None)))
+
+# --------------------------------------------------------------- exports
+for name in ("decide", "DecisionResult"):
+ check_true("__all__/%s" % name, name in laya.__all__)
+ check_true("laya.%s exists" % name, hasattr(laya, name))
+check_true("laya.structured.SchemaError is a ValueError", issubclass(structured.SchemaError, ValueError))
+
+
+print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
+for f in FAIL:
+ print(" FAIL", f)
+if not FAIL:
+ print("all structured API tests passed")
+sys.exit(1 if FAIL else 0)