lattice-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{lattice_cli-0.3.0/src/lattice_cli.egg-info → lattice_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lattice-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Deterministic combinatorial coverage for agent workflows and constrained variant surfaces.
 Author-email: Tyler Klose <tylerklose@gmail.com>
 License-Expression: Apache-2.0
@@ -143,6 +143,30 @@ the invalid rule needs multiple antecedents.
 
 `conditional` parameters are first-class schema features. The parser expands them into concrete parameter domains and the constraint engine enforces `N/A` semantics automatically.
 
+A schema with two constraints:
+
+```yaml
+model_name: checkout
+strength: 2
+parameters:
+  payment_method: [credit_card, paypal, apple_pay]
+  region: [US, UK, DE]
+  browser:
+    values: [chrome, safari, firefox]
+    weights: [0.6, 0.3, 0.1]
+constraints:
+  - type: invalid_pair
+    if: { parameter: payment_method, value: apple_pay }
+    then_not: { parameter: browser, value: firefox }
+  - type: conditional
+    parameter: card_type
+    values: [visa, mastercard]
+    parent: payment_method
+    applies_when: [credit_card]
+```
+
+Every constraint needs a `type` key. Run `lattice agent instructions` for an example of each type.
+
 ### Values keep their text
 
 Every value in a schema (the model name, parameter names and values, and constraint references) is used exactly as written. In YAML, unquoted `1.10`, `0x1F`, `.inf` or `2026-10-26T10:00:00Z` stay as typed rather than being turned into numbers or dates. The exceptions:

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/README.md

@@ -115,6 +115,30 @@ the invalid rule needs multiple antecedents.
 
 `conditional` parameters are first-class schema features. The parser expands them into concrete parameter domains and the constraint engine enforces `N/A` semantics automatically.
 
+A schema with two constraints:
+
+```yaml
+model_name: checkout
+strength: 2
+parameters:
+  payment_method: [credit_card, paypal, apple_pay]
+  region: [US, UK, DE]
+  browser:
+    values: [chrome, safari, firefox]
+    weights: [0.6, 0.3, 0.1]
+constraints:
+  - type: invalid_pair
+    if: { parameter: payment_method, value: apple_pay }
+    then_not: { parameter: browser, value: firefox }
+  - type: conditional
+    parameter: card_type
+    values: [visa, mastercard]
+    parent: payment_method
+    applies_when: [credit_card]
+```
+
+Every constraint needs a `type` key. Run `lattice agent instructions` for an example of each type.
+
 ### Values keep their text
 
 Every value in a schema (the model name, parameter names and values, and constraint references) is used exactly as written. In YAML, unquoted `1.10`, `0x1F`, `.inf` or `2026-10-26T10:00:00Z` stay as typed rather than being turned into numbers or dates. The exceptions:

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lattice-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "Deterministic combinatorial coverage for agent workflows and constrained variant surfaces."
 readme = "README.md"
 requires-python = ">=3.11"

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/agent.py

@@ -25,6 +25,56 @@ DEFAULT_PROMPT = (
     "rows; and use the rows to strengthen the plan, tests, fixtures, or visual review."
 )
 
+SCHEMA_REFERENCE = """
+Schema format, with one example of each constraint type:
+
+```yaml
+model_name: checkout
+strength: 2
+parameters:
+  user: [guest, member]
+  payment: [card, paypal, apple_pay, invoice]
+  device: [desktop, ios, android]
+  region: [us, eu]
+  currency: [usd, eur]
+  shipping: [standard, express, pickup]
+constraints:
+  # invalid_pair: these two assignments never appear in the same row.
+  - type: invalid_pair
+    if: { parameter: payment, value: apple_pay }
+    then_not: { parameter: device, value: android }
+  # bidirectional: each assignment requires the other.
+  - type: bidirectional
+    pair:
+      - { parameter: region, value: eu }
+      - { parameter: currency, value: eur }
+  # forward_dep: the source requires the target; the target may appear elsewhere.
+  - type: forward_dep
+    source: { parameter: shipping, value: pickup }
+    target: { parameter: region, value: us }
+  # conditional: defines a child parameter that only applies for some parent values.
+  - type: conditional
+    parameter: card_type
+    values: [visa, mastercard]
+    parent: payment
+    applies_when: [card]
+  # forced: this combination must appear in at least one row.
+  - type: forced
+    assignments:
+      - { parameter: user, value: guest }
+      - { parameter: device, value: ios }
+      - { parameter: shipping, value: express }
+  # higher_order: the last assignment is excluded only when all of if_all hold.
+  - type: higher_order
+    if_all:
+      - { parameter: user, value: guest }
+      - { parameter: region, value: eu }
+    then_not: { parameter: shipping, value: pickup }
+```
+
+Every constraint needs a `type` key. Each assignment is `{ parameter: <name>, value: <value> }`.
+"""
+
 GENERIC_AGENT_INSTRUCTIONS = f"""# Lattice Agent Instructions
 
 Lattice is harness-agnostic. Use these instructions in OpenClaw, Hermes, Codex, xAI-backed agents, Claude Code, or any agent that can run shell commands.
@@ -49,7 +99,7 @@ Prefer JSON or YAML on stdin:
 cat schema.json | lattice validate
 cat schema.json | lattice generate
 ```
-"""
+""" + SCHEMA_REFERENCE
 
 
 @dataclass(frozen=True)

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/cli.py

@@ -389,7 +389,7 @@ def _run_agent_command(args: argparse.Namespace) -> int:
                 )
             )
         else:
-            print(GENERIC_AGENT_INSTRUCTIONS)
+            print(GENERIC_AGENT_INSTRUCTIONS, end="")
         return 0
 
     if args.agent_command == "doctor":

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/parser.py

@@ -204,6 +204,12 @@ def _parse_constraints(
             continue
 
         constraint_type = raw_constraint.get("type")
+        if constraint_type is None:
+            errors.append(_missing_type_message(index, raw_constraint))
+            continue
+        if not isinstance(constraint_type, str):
+            errors.append(f"`constraints[{index}].type` must be a string, one of: {_CONSTRAINT_TYPE_LIST}.")
+            continue
         if constraint_type == "invalid_pair":
             if_assignment = _parse_assignment(raw_constraint.get("if"), parameters, f"`constraints[{index}].if`", errors)
             then_not = _parse_assignment(raw_constraint.get("then_not"), parameters, f"`constraints[{index}].then_not`", errors)
@@ -316,7 +322,7 @@ def _parse_constraints(
                 parsed.append(HigherOrderConstraint(if_all=tuple(parsed_if_all), then_not=parsed_then_not))
             continue
 
-        errors.append(f"`constraints[{index}]` has unknown type `{constraint_type}`.")
+        errors.append(f"`constraints[{index}]` has unknown type `{constraint_type}`. Use one of: {_CONSTRAINT_TYPE_LIST}.")
 
     return parsed
 
@@ -388,6 +394,31 @@ def _parse_weights(
     return tuple(parsed)
 
 
+# Each constraint type and the keys written beside `type`.
+_CONSTRAINT_FIELDS = {
+    "invalid_pair": "`if` and `then_not`",
+    "bidirectional": "`pair`",
+    "forward_dep": "`source` and `target`",
+    "conditional": "`parameter`, `values`, `parent` and `applies_when`",
+    "forced": "`assignments`",
+    "higher_order": "`if_all` and `then_not`",
+}
+_CONSTRAINT_TYPE_LIST = ", ".join(f"`{name}`" for name in _CONSTRAINT_FIELDS)
+
+
+def _missing_type_message(index: int, raw_constraint: dict[Any, Any]) -> str:
+    """Explains a constraint without `type`. A type name used as a key, as in
+    `- invalid_pair: {...}`, gets the correct form spelled out."""
+    shorthand = next((key for key in raw_constraint if isinstance(key, str) and key in _CONSTRAINT_FIELDS), None)
+    if shorthand is None:
+        return f"`constraints[{index}]` is missing `type`. Use one of: {_CONSTRAINT_TYPE_LIST}."
+    return (
+        f"`constraints[{index}]` is missing `type`. Write `type: {shorthand}` as its own key, "
+        f"with {_CONSTRAINT_FIELDS[shorthand]} beside it. "
+        "Run `lattice agent instructions` for an example of each type."
+    )
+
+
 _DECIMAL_TEXT = re.compile(r"[-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?")
 _INTEGER_TEXT = re.compile(r"[-+]?[0-9]+")
 

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/resources/claude/lattice-workflow/SKILL.md

@@ -35,7 +35,9 @@ parameters:
   payment: [card, apple_pay, paypal]
   cart: [empty, single, multi]
 constraints:
-  - invalid_pair: {payment: apple_pay, cart: empty}
+  - type: invalid_pair
+    if: { parameter: payment, value: apple_pay }
+    then_not: { parameter: cart, value: empty }
 ```
 
 One generated row (JSON):

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/resources/codex/lattice-workflow/SKILL.md

@@ -35,7 +35,9 @@ parameters:
   payment: [card, apple_pay, paypal]
   cart: [empty, single, multi]
 constraints:
-  - invalid_pair: {payment: apple_pay, cart: empty}
+  - type: invalid_pair
+    if: { parameter: payment, value: apple_pay }
+    then_not: { parameter: cart, value: empty }
 ```
 
 One generated row (JSON):

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice/resources/generic/lattice-workflow/SKILL.md

@@ -35,7 +35,9 @@ parameters:
   payment: [card, apple_pay, paypal]
   cart: [empty, single, multi]
 constraints:
-  - invalid_pair: {payment: apple_pay, cart: empty}
+  - type: invalid_pair
+    if: { parameter: payment, value: apple_pay }
+    then_not: { parameter: cart, value: empty }
 ```
 
 One generated row (JSON):

{lattice_cli-0.3.0 → lattice_cli-0.3.1/src/lattice_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lattice-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Deterministic combinatorial coverage for agent workflows and constrained variant surfaces.
 Author-email: Tyler Klose <tylerklose@gmail.com>
 License-Expression: Apache-2.0
@@ -143,6 +143,30 @@ the invalid rule needs multiple antecedents.
 
 `conditional` parameters are first-class schema features. The parser expands them into concrete parameter domains and the constraint engine enforces `N/A` semantics automatically.
 
+A schema with two constraints:
+
+```yaml
+model_name: checkout
+strength: 2
+parameters:
+  payment_method: [credit_card, paypal, apple_pay]
+  region: [US, UK, DE]
+  browser:
+    values: [chrome, safari, firefox]
+    weights: [0.6, 0.3, 0.1]
+constraints:
+  - type: invalid_pair
+    if: { parameter: payment_method, value: apple_pay }
+    then_not: { parameter: browser, value: firefox }
+  - type: conditional
+    parameter: card_type
+    values: [visa, mastercard]
+    parent: payment_method
+    applies_when: [credit_card]
+```
+
+Every constraint needs a `type` key. Run `lattice agent instructions` for an example of each type.
+
 ### Values keep their text
 
 Every value in a schema (the model name, parameter names and values, and constraint references) is used exactly as written. In YAML, unquoted `1.10`, `0x1F`, `.inf` or `2026-10-26T10:00:00Z` stay as typed rather than being turned into numbers or dates. The exceptions:

{lattice_cli-0.3.0 → lattice_cli-0.3.1}/src/lattice_cli.egg-info/SOURCES.txt

@@ -29,7 +29,9 @@ src/lattice_cli.egg-info/requires.txt
 src/lattice_cli.egg-info/top_level.txt
 tests/test_agent_bootstrap_matrix.py
 tests/test_cli.py
+tests/test_constraint_type_errors.py
 tests/test_constraints.py
+tests/test_docs_examples.py
 tests/test_examples.py
 tests/test_ipog.py
 tests/test_model.py

lattice_cli-0.3.1/tests/test_constraint_type_errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from lattice.parser import ValidationError, load_model
+
+FIXTURES = ROOT / "tests" / "fixtures"
+# Shared with the Ruby implementation (test/fixtures/invalid and
+# test/fixtures/golden/errors there), which must print the same messages.
+CASES = ["constraint_missing_type", "constraint_type_shorthand", "constraint_type_not_string", "unknown_constraint_type"]
+
+
+class ConstraintTypeErrorTests(unittest.TestCase):
+    def test_messages_match_goldens(self) -> None:
+        for name in CASES:
+            with self.subTest(name=name):
+                golden = json.loads((FIXTURES / "golden_errors" / f"{name}.json").read_text())
+                with self.assertRaises(ValidationError) as raised:
+                    load_model(str(FIXTURES / "invalid" / f"{name}.json"))
+                self.assertEqual(golden["errors"], raised.exception.errors)
+
+
+if __name__ == "__main__":
+    unittest.main()

lattice_cli-0.3.1/tests/test_docs_examples.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from lattice.agent import GENERIC_AGENT_INSTRUCTIONS
+from lattice.constraints import ConstraintEngine
+from lattice.parser import _CONSTRAINT_FIELDS, ValidationError, parse_model_data
+from lattice.schema_text import load_json, load_yaml
+
+# Every schema shown to users or agents must be one Lattice accepts. Checks
+# each ```yaml or ```json block that defines `parameters` in the shipped skill
+# files, the README and `lattice agent instructions`.
+FENCED_BLOCK = re.compile(r"^```(yaml|json)\n(.*?)^```", re.M | re.S)
+
+SOURCES = {
+    str(path.relative_to(ROOT)): path.read_text()
+    for path in sorted([*(ROOT / "src/lattice/resources").rglob("*.md"), *(ROOT / ".codex").rglob("*.md")])
+}
+SOURCES["README.md"] = (ROOT / "README.md").read_text()
+SOURCES["lattice agent instructions"] = GENERIC_AGENT_INSTRUCTIONS
+
+
+def schema_blocks():
+    for name, text in SOURCES.items():
+        for index, match in enumerate(FENCED_BLOCK.finditer(text), start=1):
+            if "parameters" in match.group(2):
+                yield name, index, match.group(1), match.group(2)
+
+
+class DocsExamplesTests(unittest.TestCase):
+    def test_finds_a_schema_in_every_skill_readme_and_the_agent_instructions(self) -> None:
+        found = {name for name, _index, _language, _body in schema_blocks()}
+        expected = {name for name in SOURCES if name.endswith("SKILL.md")} | {"README.md", "lattice agent instructions"}
+        self.assertEqual(set(), expected - found)
+
+    def test_agent_instructions_show_every_constraint_type(self) -> None:
+        for constraint_type in _CONSTRAINT_FIELDS:
+            self.assertIn(f"- type: {constraint_type}\n", GENERIC_AGENT_INSTRUCTIONS)
+
+    def test_every_schema_example_is_valid(self) -> None:
+        for name, index, language, body in schema_blocks():
+            with self.subTest(source=name, block=index):
+                data = load_json(body) if language == "json" else load_yaml(body)
+                try:
+                    model = parse_model_data(data)
+                except ValidationError as error:
+                    self.fail(f"{name} block {index} is not a valid schema: {' '.join(error.errors)}")
+                self.assertTrue(ConstraintEngine(model).can_complete({}), f"{name} block {index} has no valid rows")
+
+
+if __name__ == "__main__":
+    unittest.main()