hyperbase-parser-ab 0.2.0__tar.gz → 0.3.0__tar.gz

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.0] - 11-04-2026
+
+### Added
+
+- Maximum depth protection.
+- Conjunction flattening.
+- Show dependency parse tree on REPL.
+- lang_namespace parameter, defaults to False (no language namespaces in atoms).
+
+### Changed
+
+- Adopted new hyperbase API (0.10.0).
+- Adopted REPL API.
+
 ## [0.2.0] - 05-04-2026
 
 ### Changed

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hyperbase-parser-ab
-Version: 0.2.0
-Summary: Semantic Hypergraph AlphaBeta Parser
+Version: 0.3.0
+Summary: Semantic Hypergraph Alpha-Beta Parser
 Project-URL: Homepage, https://hyperquest.ai/hyperbase
 Author-email: "Telmo Menezes et al." <telmo@telmomenezes.net>
 License-Expression: MIT
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.10
-Requires-Dist: hyperbase>=0.9.0
+Requires-Dist: hyperbase>=0.10.0
 Requires-Dist: pip
 Requires-Dist: scikit-learn>=1.3.0
 Requires-Dist: spacy>=3.8.0

hyperbase_parser_ab-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "hyperbase-parser-ab"
 dynamic = ["version"]
-description = "Semantic Hypergraph AlphaBeta Parser"
+description = "Semantic Hypergraph Alpha-Beta Parser"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Information Analysis",
 ]
 dependencies = [
-    "hyperbase>=0.9.0",
+    "hyperbase>=0.10.0",
     "scikit-learn>=1.3.0",
     "spacy>=3.8.0",
     "torch>=2.0.0",

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/src/hyperbase_parser_ab/parser.py

@@ -4,16 +4,16 @@ from typing import Any, cast
 
 import hyperbase.constants as const
 import spacy
+from hyperbase.builders import build_atom, hedge
 from hyperbase.hyperedge import (
     Atom,
     Hyperedge,
     UniqueAtom,
-    build_atom,
-    hedge,
     non_unique,
     unique,
 )
 from hyperbase.parsers import Parser, ParseResult
+from hyperbase.parsers.utils import edge_depth_exceeds
 from spacy.language import Language
 from spacy.tokens import Doc, Span, Token
 
@@ -165,22 +165,67 @@ def _generate_tok_pos(atom2word: dict[Atom, tuple[str, int]], edge: Hyperedge) -
 
 
 class AlphaBetaParser(Parser):
-    def __init__(
-        self,
-        lang: str,
-        beta: str = "repair",
-        normalise: bool = True,
-        post_process: bool = True,
-        debug: bool = False,
-    ) -> None:
-        super().__init__()
-
-        self.lang: str = lang
-
-        if lang not in SPACY_MODELS:
-            raise RuntimeError(f"Language code '{lang}' is not recognized.")
-
-        models: list[str] = SPACY_MODELS[lang]
+    @classmethod
+    def accepted_params(cls) -> dict[str, dict[str, Any]]:
+        return {
+            **super().accepted_params(),
+            "lang": {
+                "type": str,
+                "default": None,
+                "description": "Language code (e.g. 'de', 'en', 'fr').",
+                "required": True,
+            },
+            "beta": {
+                "type": str,
+                "default": "repair",
+                "description": "Beta stage rules: 'strict' or 'repair'.",
+                "required": False,
+            },
+            "normalise": {
+                "type": bool,
+                "default": True,
+                "description": "Enable normalization of parsed edges.",
+                "required": False,
+            },
+            "post_process": {
+                "type": bool,
+                "default": True,
+                "description": "Enable post-processing of edges.",
+                "required": False,
+            },
+            "debug": {
+                "type": bool,
+                "default": False,
+                "description": "Enable debug message output.",
+                "required": False,
+            },
+            "lang_namespace": {
+                "type": bool,
+                "default": False,
+                "description": (
+                    "Include the language code as a namespace in atoms "
+                    "(e.g. 'apple/Cc/en' instead of 'apple/Cc')."
+                ),
+                "required": False,
+            },
+        }
+
+    def __init__(self, params: dict[str, Any] | None = None) -> None:
+        super().__init__(params)
+
+        self.lang: str = self.params["lang"]
+
+        if self.lang not in SPACY_MODELS:
+            raise RuntimeError(f"Language code '{self.lang}' is not recognized.")
+
+        beta: str = self.params.get("beta", "repair")
+        normalise: bool = self.params.get("normalise", True)
+        post_process: bool = self.params.get("post_process", True)
+        debug: bool = self.params.get("debug", False)
+        lang_namespace: bool = self.params.get("lang_namespace", False)
+        self.atom_lang: str = self.lang if lang_namespace else ""
+
+        models: list[str] = SPACY_MODELS[self.lang]
 
         self.nlp: Language | None = None
         for model in models:
@@ -191,8 +236,8 @@ class AlphaBetaParser(Parser):
         if self.nlp is None:
             models_list: str = ", ".join(models)
             raise RuntimeError(
-                f"Language '{lang}' requires one of the following language models:\n"
-                f"{models_list}."
+                f"Language '{self.lang}' requires one of the following "
+                f"language models:\n{models_list}."
             )
 
         self.alpha: Alpha = Alpha(use_atomizer=True)
@@ -202,7 +247,7 @@ class AlphaBetaParser(Parser):
         elif beta == "repair":
             self.rules = repair_rules
         else:
-            raise RuntimeError(f"unkown beta stage: {beta}")
+            raise RuntimeError(f"unknown beta stage: {beta}")
         self.normalise: bool = normalise
         self.post_process: bool = post_process
         self.debug: bool = debug
@@ -224,6 +269,11 @@ class AlphaBetaParser(Parser):
         if self.debug:
             print(msg)
 
+    def install_repl(self, session: object) -> None:
+        from hyperbase_parser_ab.repl import install
+
+        install(self, session)
+
     def parse_sentence(self, sentence: str) -> list[ParseResult]:
         # This runs spacy own sentensizer anyway...
 
@@ -264,6 +314,16 @@ class AlphaBetaParser(Parser):
             if result and len(result) == 1:
                 edge = non_unique(result[0])
 
+            # Reject pathologically deep parses before they reach the
+            # recursive transforms below (which would otherwise blow the
+            # Python stack on inputs with extreme nesting).
+            if edge is not None and edge_depth_exceeds(edge, self.max_depth):
+                self.debug_msg(
+                    f"Rejecting parse: edge depth exceeds max_depth="
+                    f"{self.max_depth} for sentence: {sent!s}"
+                )
+                return None
+
             atom2word: dict[Atom, tuple[str, int]] = {}
             if edge:
                 edge = self._apply_arg_roles(edge)
@@ -340,12 +400,12 @@ class AlphaBetaParser(Parser):
         # subject
         if dep in {"nsubj", "sb"}:
             return "s"
-        # passive subject
+        # passive subject (becomes object)
         elif dep in {"nsubjpass", "nsubj:pass"}:
-            return "p"
-        # agent
+            return "o"
+        # agent (becomes subject)
         elif dep == "agent":
-            return "a"
+            return "s"
         # object
         elif dep in {
             "obj",
@@ -361,17 +421,18 @@ class AlphaBetaParser(Parser):
         }:
             return "o"
         # indirect object
-        elif dep in {"iobj", "dative", "obl:arg", "da"}:
-            return "i"
-        # specifier
-        elif dep in {"advcl", "prep", "npadvmod", "advmod", "mo", "mnr"}:
+        elif dep in {"iobj", "dative", "obl:arg", "da"} or dep in {
+            "advcl",
+            "prep",
+            "npadvmod",
+            "advmod",
+            "mo",
+            "mnr",
+        }:
             return "x"
         # parataxis
-        elif dep in {"parataxis", "par"}:
-            return "t"
-        # interjection
-        elif dep in {"intj", "ng", "dm"}:
-            return "j"
+        elif dep in {"parataxis", "par"} or dep in {"intj", "ng", "dm"}:
+            return "?"
         # clausal complement
         elif dep in {"xcomp", "ccomp", "oc"}:
             return "r"
@@ -451,7 +512,7 @@ class AlphaBetaParser(Parser):
         elif ent_type[0] == "M":
             atom = self._build_atom_modifier(token)
         else:
-            atom = build_atom(text, et, self.lang)
+            atom = build_atom(text, et, self.atom_lang)
         return atom
 
     def _build_atom_predicate(
@@ -474,17 +535,25 @@ class AlphaBetaParser(Parser):
             else:
                 ent_type = "Pd"
 
-        return build_atom(text, ent_type, self.lang)
+        return build_atom(text, ent_type, self.atom_lang)
 
     def _build_atom_trigger(self, token: Token, ent_type: str) -> Atom:
         text: str = token.text.lower()
-        et: str = "Tv" if _is_verb(token) else ent_type
-        return build_atom(text, et, self.lang)
+
+        # indirect object
+        if token.dep_ in {"iobj", "dative", "obl:arg", "da"}:
+            et = "Ti"
+        elif _is_verb(token):
+            et = "Tv"
+        else:
+            et = ent_type
+
+        return build_atom(text, et, self.atom_lang)
 
     def _build_atom_modifier(self, token: Token) -> Atom:
         text: str = token.text.lower()
         et: str = "Mv" if _is_verb(token) else _modifier_type_and_subtype(token)
-        return build_atom(text, et, self.lang)
+        return build_atom(text, et, self.atom_lang)
 
     def _repair(self, edge: Hyperedge) -> Hyperedge:
         if edge.not_atom:
@@ -768,7 +837,7 @@ class AlphaBetaParser(Parser):
             if len(sequence) < 2:
                 return sequence, False
 
-    def sentensize(self, text: str) -> list[str]:
+    def get_sentences(self, text: str) -> list[str]:
         if self.nlp:
             doc: Doc = self.nlp(text.strip())
             return [str(sent).strip() for sent in doc.sents]
@@ -893,9 +962,34 @@ class AlphaBetaParser(Parser):
             return self._replace_argroles(edge, _ars)
         return edge
 
+    def _flatten_conjunctions(self, edge: Hyperedge) -> Hyperedge:
+        if edge.atom:
+            return edge
+        new_edge: Hyperedge = hedge(
+            [self._flatten_conjunctions(subedge) for subedge in edge]
+        )
+        if new_edge is None:
+            return edge
+        edge = new_edge
+        if edge[0].mt != "J":
+            return edge
+        connector: Hyperedge = edge[0]
+        flattened: list[Hyperedge] = [connector]
+        changed: bool = False
+        for subedge in edge[1:]:
+            if subedge.not_atom and len(subedge) >= 2 and subedge[0] == connector:
+                flattened.extend(list(subedge[1:]))
+                changed = True
+            else:
+                flattened.append(subedge)
+        if changed:
+            return hedge(flattened)
+        return edge
+
     def _post_process(self, edge: Hyperedge | None) -> Hyperedge | None:
         if edge is None:
             return None
         _edge: Hyperedge = self._fix_argroles(edge)
         _edge = self._process_colon_conjunctions(_edge)
+        _edge = self._flatten_conjunctions(_edge)
         return _edge

hyperbase_parser_ab-0.3.0/src/hyperbase_parser_ab/repl.py

@@ -0,0 +1,82 @@
+"""REPL integration for the AlphaBeta parser.
+
+Adds a pre-result hook to the Hyperbase REPL that prints the spaCy
+dependency parse tree for the current sentence. Imported lazily from
+:meth:`AlphaBetaParser.install_repl` so that this module's only purpose
+is keeping REPL-rendering code out of the parser core.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hyperbase.parsers.repl_api import PreResultHook, ReplContext
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from rich.tree import Tree
+from spacy.tokens import Token
+
+if TYPE_CHECKING:
+    from hyperbase_parser_ab.parser import AlphaBetaParser
+
+
+def _build_dependency_tree(
+    token: Token,
+    visited: set[Token] | None = None,
+) -> Tree | None:
+    """Build a Rich tree representation of a spaCy dependency parse."""
+    if visited is None:
+        visited = set()
+
+    if token in visited:
+        return None
+    visited.add(token)
+
+    label = Text()
+    label.append(token.text, style="bold white")
+    label.append(" [", style="dim")
+    label.append(f"dep_={token.dep_}", style="cyan")
+    label.append(", ", style="dim")
+    label.append(f"tag_={token.pos_}", style="yellow")
+    label.append("]", style="dim")
+
+    tree = Tree(label)
+
+    for child in token.children:
+        child_tree = _build_dependency_tree(child, visited)
+        if child_tree:
+            tree.add(child_tree)
+
+    return tree
+
+
+def _make_pre_result_hook(parser: AlphaBetaParser) -> PreResultHook:
+    """Return a pre-result hook bound to *parser*'s spaCy doc."""
+
+    def hook(ctx: ReplContext) -> None:
+        doc = getattr(parser, "doc", None)
+        if doc is None:
+            return
+        console: Console = ctx.session.console
+        for sent in doc.sents:
+            dep_tree = _build_dependency_tree(sent.root)
+            if dep_tree is None:
+                continue
+            console.print()
+            console.print(
+                Panel(
+                    dep_tree,
+                    title="[bold cyan]Dependency Parse Tree[/bold cyan]",
+                    border_style="cyan",
+                    box=box.ROUNDED,
+                )
+            )
+
+    return hook
+
+
+def install(parser: AlphaBetaParser, session: object) -> None:
+    """Register AlphaBeta-specific REPL behavior on *session*."""
+    session.register_pre_result_hook(_make_pre_result_hook(parser))  # type: ignore[attr-defined]

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/src/hyperbase_parser_ab/rules.py

@@ -1,4 +1,5 @@
-from hyperbase.hyperedge import Hyperedge, hedge
+from hyperbase import hedge
+from hyperbase.hyperedge import Hyperedge
 
 
 class Rule:

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/tests/test_parser.py

@@ -3,7 +3,8 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
-from hyperbase.hyperedge import UniqueAtom, hedge
+from hyperbase import hedge
+from hyperbase.hyperedge import UniqueAtom
 
 from hyperbase_parser_ab.parser import AlphaBetaParser
 
@@ -11,7 +12,7 @@ from hyperbase_parser_ab.parser import AlphaBetaParser
 class TestParserInitErrors:
     def test_unsupported_language_raises(self):
         with pytest.raises(RuntimeError, match="not recognized"):
-            AlphaBetaParser("xx")
+            AlphaBetaParser({"lang": "xx"})
 
     def test_unknown_beta_stage_raises(self):
         with (
@@ -21,9 +22,9 @@ class TestParserInitErrors:
             patch("spacy.util.is_package", return_value=True),
             patch("spacy.load", return_value=MagicMock()),
             patch("hyperbase_parser_ab.parser.Alpha"),
-            pytest.raises(RuntimeError, match="unkown beta stage"),
+            pytest.raises(RuntimeError, match="unknown beta stage"),
         ):
-            AlphaBetaParser("en", beta="invalid")
+            AlphaBetaParser({"lang": "en", "beta": "invalid"})
 
     def test_no_spacy_model_installed_raises(self):
         with (
@@ -34,7 +35,7 @@ class TestParserInitErrors:
             patch("hyperbase_parser_ab.parser.Alpha"),
             pytest.raises(RuntimeError, match="requires one of the following"),
         ):
-            AlphaBetaParser("en")
+            AlphaBetaParser({"lang": "en"})
 
 
 def _make_parser(beta="repair"):
@@ -46,7 +47,13 @@ def _make_parser(beta="repair"):
         patch("hyperbase_parser_ab.parser.Alpha"),
     ):
         parser = AlphaBetaParser(
-            "en", beta=beta, normalise=True, post_process=True, debug=False
+            {
+                "lang": "en",
+                "beta": beta,
+                "normalise": True,
+                "post_process": True,
+                "debug": False,
+            }
         )
     return parser
 
@@ -144,7 +151,7 @@ class TestParserRelationArgRole:
         parser.atom2token = {uatom: token}
         parser.orig_atom = {uatom: uatom}
         parser.depths = {uatom: 1}
-        assert parser._relation_arg_role(edge) == "p"
+        assert parser._relation_arg_role(edge) == "o"
 
     def test_indirect_object(self):
         parser = _make_parser()
@@ -155,7 +162,7 @@ class TestParserRelationArgRole:
         parser.atom2token = {uatom: token}
         parser.orig_atom = {uatom: uatom}
         parser.depths = {uatom: 1}
-        assert parser._relation_arg_role(edge) == "i"
+        assert parser._relation_arg_role(edge) == "x"
 
     def test_specifier(self):
         parser = _make_parser()
@@ -244,6 +251,76 @@ class TestParserDebug:
         assert capsys.readouterr().out == ""
 
 
+class TestParserFlattenConjunctions:
+    def test_flatten_atom_unchanged(self):
+        parser = _make_parser()
+        atom = hedge("red/Ca/en")
+        assert parser._flatten_conjunctions(atom) == atom
+
+    def test_flatten_no_conjunction_unchanged(self):
+        parser = _make_parser()
+        edge = hedge("(runs/Pd/en cat/Cc/en dog/Cc/en)")
+        assert parser._flatten_conjunctions(edge) == edge
+
+    def test_flatten_simple_conjunction_unchanged(self):
+        """A flat conjunction with no nested conjunctions stays the same."""
+        parser = _make_parser()
+        edge = hedge("(,/J red/Ca/en green/Ca/en blue/Ca/en)")
+        assert parser._flatten_conjunctions(edge) == edge
+
+    def test_flatten_nested_same_connector(self):
+        """(,/J red (,/J green blue)) → (,/J red green blue)"""
+        parser = _make_parser()
+        edge = hedge("(,/J red/Ca/en (,/J green/Ca/en blue/Ca/en))")
+        expected = hedge("(,/J red/Ca/en green/Ca/en blue/Ca/en)")
+        assert parser._flatten_conjunctions(edge) == expected
+
+    def test_flatten_nested_different_connector_unchanged(self):
+        """Nested conjunction with a different connector should NOT be flattened."""
+        parser = _make_parser()
+        edge = hedge("(,/J red/Ca/en (and/J/en green/Ca/en blue/Ca/en))")
+        assert parser._flatten_conjunctions(edge) == edge
+
+    def test_flatten_recursive_bottom_up(self):
+        """Multiple levels of nesting should all collapse."""
+        parser = _make_parser()
+        edge = hedge("(,/J red/Ca/en (,/J green/Ca/en (,/J blue/Ca/en yellow/Ca/en)))")
+        expected = hedge("(,/J red/Ca/en green/Ca/en blue/Ca/en yellow/Ca/en)")
+        assert parser._flatten_conjunctions(edge) == expected
+
+    def test_flatten_multiple_nested_conjunctions(self):
+        """(,/J (,/J a b) (,/J c d)) → (,/J a b c d)"""
+        parser = _make_parser()
+        edge = hedge("(,/J (,/J a/Ca/en b/Ca/en) (,/J c/Ca/en d/Ca/en))")
+        expected = hedge("(,/J a/Ca/en b/Ca/en c/Ca/en d/Ca/en)")
+        assert parser._flatten_conjunctions(edge) == expected
+
+    def test_flatten_inside_outer_edge(self):
+        """A nested conjunction inside a non-conjunction outer edge is still
+        flattened bottom-up."""
+        parser = _make_parser()
+        edge = hedge(
+            "(runs/Pd/en cat/Cc/en (,/J red/Ca/en (,/J green/Ca/en blue/Ca/en)))"
+        )
+        expected = hedge(
+            "(runs/Pd/en cat/Cc/en (,/J red/Ca/en green/Ca/en blue/Ca/en))"
+        )
+        assert parser._flatten_conjunctions(edge) == expected
+
+    def test_flatten_mixed_connectors_partial(self):
+        """Only the matching nested conjunctions should be flattened."""
+        parser = _make_parser()
+        edge = hedge(
+            "(,/J red/Ca/en (,/J green/Ca/en blue/Ca/en)"
+            " (and/J/en yellow/Ca/en purple/Ca/en))"
+        )
+        expected = hedge(
+            "(,/J red/Ca/en green/Ca/en blue/Ca/en"
+            " (and/J/en yellow/Ca/en purple/Ca/en))"
+        )
+        assert parser._flatten_conjunctions(edge) == expected
+
+
 class TestParserReset:
     def test_reset_clears_state(self):
         parser = _make_parser()

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/tests/test_parser_helpers.py

@@ -2,7 +2,8 @@
 
 from unittest.mock import MagicMock
 
-from hyperbase.hyperedge import UniqueAtom, hedge
+from hyperbase import hedge
+from hyperbase.hyperedge import UniqueAtom
 
 from hyperbase_parser_ab.parser import (
     _builder_type_and_subtype,

{hyperbase_parser_ab-0.2.0 → hyperbase_parser_ab-0.3.0}/tests/test_rules.py

@@ -1,4 +1,4 @@
-from hyperbase.hyperedge import hedge
+from hyperbase import hedge
 
 from hyperbase_parser_ab.rules import Rule, apply_rule, repair_rules, strict_rules
 

hyperbase_parser_ab-0.2.0/VERSION

@@ -1 +0,0 @@
-0.2.0