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.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat(structured): schema-driven decisions via decide() (#280)
Emiliano G.O.a5f3514fcdf9
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex bd62feeb..c731c99f 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -84,6 +84,8 @@ jobs:python tests/test_batch.pypython tests/test_hooks.pypython tests/test_hooks_api.py+ python tests/test_structured.py+ python tests/test_structured_api.pypython tests/test_download.pypython tests/test_shortlist.pypython tests/test_decision_model.pydiff --git a/README.md b/README.mdindex 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 PresetsLaya provides pre-tuned question schemas for immediate production use:diff --git a/docs/structured.md b/docs/structured.mdnew file mode 100644index 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__.pyindex 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.pyindex 41b205b6..285885ce 100644--- a/laya/agent.py+++ b/laya/agent.py@@ -865,6 +865,18 @@ class Agent(HookRegistry):passreturn 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_onediff --git a/laya/onnx_agent.py b/laya/onnx_agent.pyindex 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_onediff --git a/laya/router.py b/laya/router.pyindex ccbe5980..6becc646 100644--- a/laya/router.py+++ b/laya/router.py@@ -582,6 +582,18 @@ class Router(HookRegistry):raisereturn 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 selfdiff --git a/laya/structured.py b/laya/structured.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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)