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.

docs(structured): make the subset table the schema the compiler maps

Aashishefdbc3786ca7
diff --git a/docs/structured.md b/docs/structured.md
index 97a3d3c2..ede03281 100644
--- a/docs/structured.md
+++ b/docs/structured.md
@@ -40,14 +40,28 @@ ticket = agent.decide("I was charged twice, refund me.", schema=Ticket)
The top level must be an object with `properties`. Each property becomes one question.
+Every row below is a real schema: `tests/test_structured_docs.py` compiles the first column and
+asserts the question the compiler actually produces, so this table cannot drift from the code. A cell
+is either a property schema on its own, or a call to an entry point.
+
| 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 | |
+| `{"enum": ["billing", "support"]}` | `choice` | the chosen value, with its original type |
+| `{"const": "billing"}` | `choice` | that one value |
+| `{"type": "boolean"}` | `noul` | `true` / `false` |
+| `{"type": "integer", "minimum": 0, "maximum": 5}` | `score` | the highest-probability level, as an integer |
+| `{"type": "number", "minimum": 0, "maximum": 5}` | `score` | the level, as an integer |
+| `{"type": "string", "enum": ["low", "high"], "description": "How urgent?"}` | `choice` | `How urgent?` is the question wording |
+| `{"anyOf": [{"enum": ["x", "y"]}, {"type": "null"}]}` | `choice` | as the plain `enum` row; no answer leaves the key out |
+| `{"oneOf": [{"type": "boolean"}, {"type": "null"}]}` | `noul` | as the plain `boolean` row |
+| `{"type": ["integer", "null"], "minimum": 1, "maximum": 3}` | `score` | as the plain bounded-integer row |
+
+`Literal[...]` and `Optional[...]` are the pydantic spellings of the `enum` and `anyOf` rows:
+`questions_from_pydantic` renders them to those shapes and the same rows apply.
+
+`title` is **not** read. pydantic puts one on every field of `model_json_schema()` whether you asked
+for it or not, and a per-property name cannot label the per-option choices a question is built from,
+so the wording lever is `description` — see *How it maps internally* below.
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`.
@@ -55,17 +69,34 @@ 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:
+(a `ValueError`) naming the exact path. Each row is executed too, with the field named `name`:
-| case | message shape |
+| property schema | message |
+|---|---|
+| `{"type": "string"}` | `properties.name: a free string cannot be a fixed option set; use 'enum' or a boolean` |
+| `{"type": "array", "items": {"type": "string"}}` | `properties.name: arrays are not supported; ask one field per element` |
+| `{"type": "object", "properties": {"inner": {"type": "boolean"}}}` | `properties.name: nested objects are not supported; flatten the schema` |
+| `{"$ref": "#/definitions/node"}` | `properties.name: $ref/recursion is not supported; flatten the schema` |
+| `{"enum": [1, "1"]}` | `properties.name: enum values produce duplicate choice labels` |
+| `{"enum": []}` | `properties.name: 'enum' must not be empty` |
+| `{"type": "number"}` | `properties.name: a numeric field needs integer 'minimum' and 'maximum' to become a score` |
+| `{"type": "integer", "minimum": 5, "maximum": 2}` | `properties.name: 'maximum' 2 is below 'minimum' 5` |
+| `{"type": "integer", "minimum": 0, "maximum": 10}` | `properties.name: 11 levels exceeds MAX_SCORE_LEVELS=10; narrow the range or use an enum` |
+| `{"anyOf": [{"type": "string"}, {"type": "integer"}]}` | `properties.name: only 'Optional[...]' unions (one non-null branch) are supported, got 2` |
+| `{"type": ["string", "integer"]}` | `properties.name: 'type' has multiple non-null types; unions are not supported` |
+| `{"format": "date"}` | `properties.name: unsupported schema {'format': 'date'}` |
+| `"boolean"` | `properties.name: property must be an object, got str` |
+
+The entry points themselves reject these:
+
+| call | message |
|---|---|
-| 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` |
-| enum values with the same choice label, such as `1` and `"1"` | `properties.name: enum values produce duplicate choice labels` |
-| 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 |
+| `plan_from_json_schema("not a schema")` | `expected a JSON schema object, got str` |
+| `plan_from_json_schema({"type": "object"})` | `the top level must be an object with 'properties'` |
+| `plan_from_json_schema({"type": "object", "properties": {}})` | `'properties' must be a non-empty object` |
+| `plan_from_json_schema({"type": "object", "properties": {"p%d" % i: {"type": "boolean"} for i in range(33)}})` | `33 properties exceeds MAX_PROPERTIES=32` |
+| `plan_from_json_schema({"type": "object", "properties": {"name": {"enum": ["v%d" % i for i in range(33)]}}})` | `properties.name: 33 options exceeds MAX_OPTIONS=32` |
+| `decide(None, "I was charged twice.", schema=42)` | `expected a JSON schema dict or a pydantic model, got int` |
Limits: `MAX_PROPERTIES = 32`, `MAX_OPTIONS = 32`, `MAX_SCORE_LEVELS = 10`.
@@ -120,6 +151,9 @@ if result.confidence["department"] < 0.6:
- 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.
+- A `null` branch is dropped before the field is planned, so `Optional[X]` asks exactly the question
+ `X` asks. The field's key is simply absent from the values when there is no answer for it, which is
+ what makes it safe to declare a field optional without changing what the model sees.
## See also