more subtypes

Author: telmomenezes

docs/manual/notation.md

@@ -92,6 +92,14 @@ Specifications can be other relations, for example in "Maria plays chess when it
 (plays/P.sox maria/C chess/C (when/T (rains/P.o it/C)))
 ```
 
+**Every argument filling the specification role (`x`) must be of type specifier (`S`).** Specifiers are produced by triggers (`(T [CR])` → `S`), so a specification is normally introduced by a trigger word, as in `(in/Tt ...)` or `(when/Tt ...)` above. When a specification has no natural trigger word in the surface text — for example a bare indirect object — the argument must still be turned into an `S` by enclosing it in the appropriate special trigger atom `_/T*/.` (see [Special atoms](#special-atoms)). For instance, "Maria gave Peter a book" has Peter as a recipient with no preposition:
+
+```
+(gave/P.sox maria/Cp book/Cc (_/Ti/. peter/Cp))
+```
+
+Here `(_/Ti/. peter/Cp)` is a specifier of indirect-object subtype, satisfying the requirement that the `x` argument be of type `S`.
+
 ### Builders
 
 In builders, the two argument roles are used to identify the main concept and the auxiliary concept
@@ -125,31 +133,48 @@ The following tables present the subtypes that SH semantic parsers are expected
 | Cq | quantitative | 27/Cn |
 | Ca | adjective | 27/Ca |
 | Cd | determinant | some/Cd |
+| Cw | interrogative / wh (nominal) | who/Cw, what/Cw, which/Cw |
+| Ce | demonstrative pronoun | this/Ce, that/Ce |
+| Cg | nominalized verb / gerund | swimming/Cg |
 | Cx | unclassified | |
 
 ### Predicate
 
+`Pv` is the default declarative verbal predicate. The mood/kind subtypes below take precedence when they apply; a predicate carries exactly one single-character subtype.
+
 | Code | Subtype | Example |
 |------|---------|---------|
-| Pv | verbal | is/Pv |
+| Pv | verbal (declarative, default) | is/Pv |
+| Pi | interrogative | is/Pi (Is the sky blue?) |
+| Pj | imperative / jussive | close/Pj (Close the door) |
+| Pn | nominal / copular | non-verbal / copula-drop predicate |
+| Pe | existential | there is/are |
 | Px | unclassified | |
 
 ### Builder
 
 | Code | Subtype | Example |
 |------|---------|---------|
+| Bp | genitive / relational | of/Bp.ma (capital of France) |
+| Bm | partitive / measure | cup of coffee, slice of bread |
 | Bx | unclassified | |
 
+Appositives ("Obama, the president") are *not* builders: express them with the generic conjunction `:/J/.`, e.g. `(:/J/. obama/Cp (the/Md president/Cc))`.
+
 ### Modifier
 
 | Code | Subtype | Example |
 |------|---------|---------|
 | Md | determinant | the/Md |
 | Ma | adjective | green/Ma |
 | Mq | quantitative | 100/Mq |
-| Mm | modal | will/Mv |
+| Mm | modal / tense / auxiliary | will/Mm, was/Mm |
+| Mb | adverbial / manner | quickly/Mb, carefully/Mb |
+| Mg | degree / intensifier | very/Mg, more/Mg, too/Mg |
 | Mn | negation | not/Mn |
 | Mp | possessive | my/Mp |
+| Me | demonstrative determiner | this/Me, that/Me |
+| Mw | interrogative determiner | which/Mw, whose/Mw |
 | Mx | unclassified | |
 
 ### Trigger
@@ -184,4 +209,29 @@ Special atoms are annotated with the reserved `.` namespace.
 |------|---------|---------|
 | +/B/. | Define compound nouns | (+/B.am/. alan/Cp turing/Cp) |
 | :/J/. | Generic conjunction | |
-| _/Ti/. | Indirect object | |
+
+### Special trigger atoms
+
+There is one special trigger atom per trigger subtype. Use them to turn a bare concept or relation into a specifier (`S`) when a specification argument (the `x` role of a predicate) has no natural trigger word in the surface text. The subtype is chosen to match the semantic role the specification plays.
+
+| Atom | Subtype | Example |
+|------|---------|---------|
+| _/Tt/. | temporal | (_/Tt/. monday/Cc) |
+| _/Tl/. | locative | (_/Tl/. berlin/Cp) |
+| _/Ti/. | indirect object | (_/Ti/. peter/Cp) |
+| _/Ta/. | passive actor / agent | (_/Ta/. dog/Cc) |
+| _/Tb/. | beneficiary | (_/Tb/. him/Ci) |
+| _/Ts/. | source / ablative | (_/Ts/. paris/Cp) |
+| _/Tn/. | manner / means / instrument | (_/Tn/. hammer/Cc) |
+| _/Tw/. | comitative | (_/Tw/. john/Cp) |
+| _/Tr/. | reference / topic | (_/Tr/. politics/Cc) |
+| _/Tq/. | quantitative / measure | (_/Tq/. (5/Mq percent/Cc)) |
+| _/Tv/. | privative / negative | (_/Tv/. money/Cc) |
+| _/Tf/. | conditional | (_/Tf/. (rains/Pv.s it/Ci)) |
+| _/Tc/. | causal | (_/Tc/. rain/Cc) |
+| _/Tp/. | purpose / final | (_/Tp/. safety/Cc) |
+| _/To/. | result / consecutive | (_/To/. victory/Cc) |
+| _/Tg/. | concessive | (_/Tg/. rain/Cc) |
+| _/Te/. | comparative | (_/Te/. lion/Cc) |
+| _/Td/. | declarative complementizer | (_/Td/. (won/Pv.s she/Ci)) |
+| _/Tx/. | unclassified | (_/Tx/. thing/Cc) |

src/hyperbase/correctness.py

@@ -10,15 +10,21 @@
     from hyperbase.hyperedge import Atom, Hyperedge
 
 
-def check_correctness(edge: Hyperedge) -> dict[Hyperedge, list[tuple[str, str, int]]]:
+def check_correctness(
+    edge: Hyperedge, strict: bool = False
+) -> dict[Hyperedge, list[tuple[str, str, int]]]:
     """Check correctness of a hyperedge, returning errors keyed by subedge.
 
     Each error is ``(code, message, severity)``. Correctness failures are hard
     grammar violations, so they all carry severity ``0`` (the most serious).
+
+    When ``strict`` is ``True``, additional grammar rules are enforced: every
+    argument filling a predicate's specification role (``x``) must be of type
+    specifier (``S``). Default (``strict=False``) behaviour is unchanged.
     """
     if edge.atom:
         return _check_atom(edge)  # type: ignore[arg-type]
-    return _check_edge(edge)
+    return _check_edge(edge, strict)
 
 
 def _check_atom(atom: Atom) -> dict[Hyperedge, list[tuple[str, str, int]]]:
@@ -42,7 +48,9 @@ def _check_atom(atom: Atom) -> dict[Hyperedge, list[tuple[str, str, int]]]:
     return output
 
 
-def _check_edge(edge: Hyperedge) -> dict[Hyperedge, list[tuple[str, str, int]]]:
+def _check_edge(
+    edge: Hyperedge, strict: bool = False
+) -> dict[Hyperedge, list[tuple[str, str, int]]]:
     output: dict[Hyperedge, list[tuple[str, str, int]]] = {}
     errors: list[tuple[str, str]] = []
 
@@ -96,6 +104,27 @@ def _check_edge(edge: Hyperedge) -> dict[Hyperedge, list[tuple[str, str, int]]]:
             if at not in {EdgeType.CONCEPT, EdgeType.RELATION, EdgeType.SPECIFIER}:
                 e = f"predicate argument '{arg}' of '{edge}' has incorrect type: {at}"
                 errors.append(("pred-arg-bad-type", e))
+        # strict: every specification-role (x) argument must be a specifier (S)
+        if strict:
+            try:
+                ars = edge.argroles()
+            except RuntimeError:
+                ars = ""
+            for i, arg in enumerate(edge[1:]):
+                if (
+                    i < len(ars)
+                    and ars[i] == const.ArgRole.SPECIFICATION
+                    and arg.mtype() != EdgeType.SPECIFIER
+                ):
+                    errors.append(
+                        (
+                            "spec-arg-not-specifier",
+                            f"specification argument '{arg}' of '{edge}' must "
+                            f"be a specifier (type 'S'), but has type "
+                            f"{arg.mtype()}. Wrap it in a trigger (e.g. a "
+                            f"special trigger atom like _/Tt/.).",
+                        )
+                    )
     # check if conjunction structure is correct
     elif ct == EdgeType.CONJUNCTION and len(edge) < 3:
         errors.append(
@@ -165,7 +194,7 @@ def _check_edge(edge: Hyperedge) -> dict[Hyperedge, list[tuple[str, str, int]]]:
         output[edge] = [(code, msg, 0) for code, msg in errors]
 
     for subedge in edge:
-        output.update(check_correctness(subedge))
+        output.update(check_correctness(subedge, strict))
 
     return output
 
@@ -212,7 +241,10 @@ def _visit(current_edge: Hyperedge) -> None:
             connector_type = current_edge[0].type()
             if len(current_edge) >= 2:
                 target_mt = current_edge[1].mt
-                if connector_type in {"Ma", "Md", "Mq", "Mp"} and target_mt != "C":
+                if (
+                    connector_type in {"Ma", "Md", "Mq", "Mp", "Me", "Mw"}
+                    and target_mt != "C"
+                ):
                     current_errors.append(
                         (
                             f"bad-{connector_type.lower()}-target",
@@ -225,10 +257,31 @@ def _visit(current_edge: Hyperedge) -> None:
                 elif connector_type == "Mm" and target_mt != "P":
                     current_errors.append(
                         (
-                            "bad-mm-target",
-                            f"Modifier '{current_edge}' of type 'Mm' should only be "
-                            "applied to predicates (type 'P'), but its target "
-                            f"'{current_edge[1]}' has type '{target_mt}'.",
+                            f"bad-{connector_type.lower()}-target",
+                            f"Modifier '{current_edge}' of type '{connector_type}' "
+                            "should only be applied to predicates (type 'P'), but its "
+                            f"target '{current_edge[1]}' has type '{target_mt}'.",
+                            3,
+                        )
+                    )
+                elif connector_type == "Mb" and target_mt not in {"P", "T"}:
+                    current_errors.append(
+                        (
+                            f"bad-{connector_type.lower()}-target",
+                            f"Modifier '{current_edge}' of type '{connector_type}' "
+                            "should only be applied to predicates/triggers "
+                            f"(type 'P' or 'T'), but its target '{current_edge[1]}' "
+                            f"has type '{target_mt}'.",
+                            3,
+                        )
+                    )
+                elif connector_type == "Mg" and target_mt not in {"C", "M"}:
+                    current_errors.append(
+                        (
+                            "bad-mg-target",
+                            f"Modifier '{current_edge}' of type 'Mg' should only be "
+                            "applied to adjectives/adverbs (type 'C' or 'M'), but its "
+                            f"target '{current_edge[1]}' has type '{target_mt}'.",
                             3,
                         )
                     )

src/hyperbase/hyperedge.py

@@ -428,10 +428,12 @@ def arguments_with_role(self, argrole: str) -> list[Hyperedge]:
                 edges.append(self[pos + 1])
         return edges
 
-    def check_correctness(self) -> dict[Hyperedge, list[tuple[str, str, int]]]:
+    def check_correctness(
+        self, strict: bool = False
+    ) -> dict[Hyperedge, list[tuple[str, str, int]]]:
         from hyperbase.correctness import check_correctness
 
-        return check_correctness(self)
+        return check_correctness(self, strict=strict)
 
     def normalise(self) -> Hyperedge:
         from hyperbase.transforms import _propagate_root_text, normalise

src/hyperbase/parsers/correctness.py

@@ -8,6 +8,11 @@
 original tokens. The third value in each error tuple is a severity (lower is
 worse): ``0`` for hard correctness failures, ``1`` for token-mismatch issues,
 ``2`` for argrole problems, ``3`` for junction issues.
+
+When ``strict`` is ``True``, the underlying :func:`check_correctness` also
+enforces that every predicate specification-role (``x``) argument is a
+specifier (``S``), emitting a ``spec-arg-not-specifier`` failure otherwise.
+Default (``strict=False``) behaviour is unchanged.
 """
 
 from hyperbase.correctness import check_structural_quality
@@ -18,11 +23,12 @@
 def check_parse_correctness(
     edge: Hyperedge,
     tokens: list[str],
+    strict: bool = False,
 ) -> dict[str | Hyperedge, list[tuple[str, str, int]]]:
 
     # Hard grammar failures (severity 0), keyed by subedge.
     errors: dict[str | Hyperedge, list[tuple[str, str, int]]] = {
-        k: list(v) for k, v in edge.check_correctness().items()
+        k: list(v) for k, v in edge.check_correctness(strict=strict).items()
     }
 
     structural_errors = check_structural_quality(edge)

tests/test_parse_correctness.py

@@ -324,3 +324,70 @@ def test_check_correctness_severity(self):
                     assert err[2] == 0
                     found = True
         assert found, "Should have build-2-args with severity 0"
+
+
+def _codes(errors):
+    return {code for v in errors.values() for code, _msg, _sev in v}
+
+
+class TestStrictMode:
+    """Strict mode enforces that x-role arguments are specifiers (S)."""
+
+    def test_strict_flags_bare_specification_argument(self):
+        # "peter" fills the x slot but is a bare concept, not a specifier
+        edge = hedge("(gave/Pv.sox maria/Cp book/Cc peter/Cp)")
+        assert edge
+        errors = check_parse_correctness(edge, [], strict=True)
+        assert "spec-arg-not-specifier" in _codes(errors)
+
+    def test_strict_error_has_severity_zero(self):
+        edge = hedge("(gave/Pv.sox maria/Cp book/Cc peter/Cp)")
+        assert edge
+        errors = check_parse_correctness(edge, [], strict=True)
+        severities = [
+            sev
+            for v in errors.values()
+            for code, _msg, sev in v
+            if code == "spec-arg-not-specifier"
+        ]
+        assert severities == [0]
+
+    def test_default_mode_does_not_flag_bare_specification(self):
+        # Same edge, default (non-strict) mode: behaviour unchanged.
+        edge = hedge("(gave/Pv.sox maria/Cp book/Cc peter/Cp)")
+        assert edge
+        errors = check_parse_correctness(edge, [])
+        assert "spec-arg-not-specifier" not in _codes(errors)
+
+    def test_strict_passes_wrapped_specification(self):
+        # Wrapping the recipient in a special trigger atom makes it an S.
+        edge = hedge("(gave/Pv.sox maria/Cp book/Cc (_/Ti/. peter/Cp))")
+        assert edge
+        errors = check_parse_correctness(edge, [], strict=True)
+        assert "spec-arg-not-specifier" not in _codes(errors)
+
+    def test_strict_allows_relation_specification(self):
+        # A trigger applied to a relation is an S and is accepted in the x slot.
+        edge = hedge("(plays/Pv.sox maria/Cp chess/Cc (when/Tt (rains/Pv.s it/Ci)))")
+        assert edge
+        errors = check_parse_correctness(edge, [], strict=True)
+        assert "spec-arg-not-specifier" not in _codes(errors)
+
+
+class TestNewSubtypeModifierRules:
+    """Soft modifier-target checks cover the newly added modifier subtypes."""
+
+    def test_interrogative_determiner_on_predicate_flagged(self):
+        edge = hedge("(which/Mw (ran/Pv.sox he/Ci))")
+        assert edge
+        assert "bad-mw-target" in _codes(check_parse_correctness(edge, []))
+
+    def test_demonstrative_determiner_on_concept_ok(self):
+        edge = hedge("(this/Me book/Cc)")
+        assert edge
+        assert "bad-me-target" not in _codes(check_parse_correctness(edge, []))
+
+    def test_manner_adverb_on_concept_flagged(self):
+        edge = hedge("(quickly/Mb sky/Cc)")
+        assert edge
+        assert "bad-mb-target" in _codes(check_parse_correctness(edge, []))